コード
doc/CODE.mdとengineering/code/README.mdはほぼ同一だったため、推敲の進んだdoc/CODE.mdを採用した。doc/CODE_SIMPLE.mdはdoc/CODE.mdと完全一致のため取り込んでいない。
https://google.github.io/eng-practices/ https://google.github.io/styleguide/pyguide.html
このディレクトリ
- スタイルガイドとルール — ルールを定めるときの基準(書籍 第8章)
- バグ — テストコードで検知できない可能性のあるもの
フォーマッター
よい設定
カスタマイズをできるだけしない
バージョンアップが楽である
formatterの変更が楽である
よい対応
1行の上限超えのために変な改行ではなく、一時変数に置く
複雑性軽減のために小さなプライベートメソッドをたくさん作らずに共通化できそうなものは共通のメソッドにする
複雑性軽減のために何回もループを回さない
姿勢
問題(issue)を見つけたとき
すでに似たようなissueがないか
似たようなissueがないときだけissueを作成する
文句は言わず、自分が直す
issueを作成するだけになっていないか
issueを作成するのと対応する数のバランス
ほとんどissueを作成するだけの人とどんどん直していく人どちらと一緒に働きたいか
issueを作成して、どんどん修正する
直せるものはどんどん直す
他の人が変なことをしているからではなく、自分が変なことをしているからと考える
デッドコード(使われていないコード・使われていない分岐)を見つけたとき
使われていないことを確認し、ついでに削除する
あとで使う場合はそのときに作成する
デッドコードのように見えて、コメント不足によりデッドコードと勘違いしそうなものにはコメントを追記する
日々の成果
毎日プッシュすることで現状を共有する
推測だけではなく実行する
原則そのものは原則にある。 ここではコードを書く場面での具体を置く。
簡単に実行できるものは、実行して挙動を確認する
実際のユースケースやパターンのデータで確かめる
「実際のデータで」が要点。 手で作った都合のよい入力では、 推測を確かめたことにならない。
ブランチ
手間のかかるブランチ運用は行わず、masterブランチへのプルリクを作成する
マージ前に自動テストで挙動が確認される
masterブランチにマージされるとすぐにデプロイされてもよいようにする
リポジトリ
モノリスにすることで開発環境で複数リポジトリを通じたテストをしやすくする
言語・ツール、ライブラリー、フレームワーク特有の機能
最小限にして、できるだけ独立させ、ポータビリティーを持たせる
最小限にして、セキュリティパッチ・バージョンアップの機会を最小限に減らす
最小限にして、言語、ツール、ライブラリー、フレームワーク内で使っていないソースが最小限にする
定期的に最新のバージョンにアップデートされているかどうか
バージョンアップで削除される可能性の高いレアな機能を使っていないか
新しいバージョンでは弊害となる使い方をしていないか
シンプルに長く一般的に使われている機能だけを使っているかどうか
オリジナルのフレームワーク等を使っていないかどうか
世間一般的な使い方のものではなく、独特な少数しか使っていないものではないか
複雑な実装・思想よりもシンプルな実装・思想をしているものが結局は残る
命名
重複コードをあちこちに書かない
特定のページ用に限定せずに実行している内容を元に他で使いやすいように命名する
他の箇所で使われるようになったときにリネームを不要にする
メソッド名ではなく、ディレクトリ、ファイル名であらかじめ情報を限定することでメソッド名をシンプルにする
1や2等の数字やnew等を命名に使わない
先を見る
将来のリファクタや負の遺産をレビュー時点で解消しておく
リファクタリングを想定した絶対パスかどうか
リファクタリングでファイルやディレクトリを移動したときに一括置換できるようになっているかどうか
動的にキーを生成していないか
後で使用箇所を検索したときにヒットしないような実装になっていないか
後で使用箇所を検索したときに依存箇所が一意的(検索結果に関係ないものが混ざらない)で分かりやすいかどうか
コードを書いた人もレビュアーもいなくなったときに分かりやすく読みやすいかどうか
数年経ったときの注意点が書かれているかどうか(コード作者自身のためでもある)
コードを書いた人もレビュアーもいなくなったときの注意点が書かれているかどうか
テストコードを考慮する
テストコードの書きやすさも考慮してレビューできているか
外部との通信はラッパーになっているかどうか
レビュー時にソースを書き換えておかしな挙動にしてもテストがちゃんと失敗するかどうか
ソースを書き換えて挙動を変えてテストが失敗するかどうか
ライブラリ・フレームワーク・言語・組織・グループを超えた一貫性とシンプルさ
不必要にライブラリ・フレームワーク・言語の機能を使って複雑になっていないか
他のライブラリ・フレームワーク・言語しか知らない人が後で保守することになっても分かりやすいかどうか
ライブラリ・フレームワーク・言語・組織・グループを超えた一貫性とシンプルさ
直感的
誰でも正しく使うことが楽
そのライブラリ・フレームワーク・言語・組織・グループに詳しくなくても楽に使うことができる
チェック・バリデーション
チェックやバリデーションは早めに実施して、後に実施したり何回もいろんな箇所で重複して行っていないかどうか
APIはymlでパラメーターのバリデーションをして、コントローラーではしない
1リクエスト内で同じ値を何回も重複チェックしていないかどうか
※他から呼び出されることがあるAPI等のチェックは必要
フェーズによって進化させているか
引数が増えてきたらまとめて渡すように修正する
必要な引数が増えそうな場合は一つ一つ変数にして引数に渡すのではなくそのまま渡す
使い方がおかしくないか
静的解析ツールの意図と違って強引な指摘回避をしていないかどうか
本来の用途とは違う使い方をしていないか
公式ドキュメントの注記等を考慮していない使い方をしていないか
混在していないか
いろんな処理内容が混ざっていないかどうか
各種単一処理のメソッド呼び出しをまとめるメソッドは混ざってもよい
コンテキスト
否定ではなく肯定で書けるものを否定で書いていないか
条件文をメソッドに切り出してシンプルにできないか
読みやすさ
強引にDRYにして、逆に読みにくくなっていないか
意味のまとまり毎に改行が適切にあり、ぱっと見で読みやすいかどうか
実装のしやすさよりも読みやすさが考えられているか
実装は1回でも、読まれるのは何回もあり得ることが考えられているかどうか
呼び出しのネスト階層が深くなりすぎていないか
使っていないものはメンテしているか
デッドコードがないかどうか
何も考えずにコピペして、本当に必要かどうかを考え、検証できているか
プルリクに複数の変更が混ざっていないか
複数の変更が混ざっているとリバートする際に面倒になる
プルリクが大きいとレビューに時間がかかり、リリースサイクルが大きくなる
レビュアーが確認すべきことが多くなるとレビューの質が下がる
小さな変更をしっかりレビューして、素早くリリースしていく
新規ツール、ライブラリー、フレームワークの選定
新しい・流行っているというだけで安易に採用しない
本当に楽かどうか
計測
異常値は除く
1回ではなく、平均で計測する
常に確認する習慣
平均で見るのは、ばらつきを均すため。 ただし利用者から見た遅さを評価する場面では平均を使わない。 そちらは性能を測ると ユーザー体験の目標にある。
費用対効果
生存期間が短いからといってひどく汚いソースにしてはいけない
ひどく汚いソースを書く人は実装が遅く、保守性の低いコードを書く
生存期間が短いものを不必要に壮大にしなくてよい
どれだけのコード量でどれだけの機能を提供できるか
リポジトリをcloneしたときのことを考える
他に影響しないようにいろんな箇所に似たようなコードがあり、リポジトリのサイズが不要に大きくなっていないか
リポジトリの大きさは処理時間、CI、デプロイが時間が長くなり、必要なリソースも増え、コストも高くなる
問題の検知と修正
早ければ早い方がよい
実装時に検知と修正できているかどうか
リリース後しばらくたって、問題が発覚したりしていないか
大丈夫問題は起こらないの福島原発の件
Google+の画像内の個人情報の件
継承や内包より利用
継承は使わない
何層にも続く継承は可読性が極めて低くなる
継承先への変数を暗黙的に使わない
1層目の変数を4層目で使うなどしない
何層にも続く内包は可読性が極めて低くなる
暗黙的な内包は使わない
1層目の内包したものを4層目で使うなどしない
やっていることから命名して分けたものを使うとこだけで読み込んで利用する
コメント
実装中の今の自分のために書いていないか
自分がいなくなったときに疑問が出てきたときのため
なぜそうなっているかを忘れた将来の自分のため
注意したこと
コメントがないと変更されそうな重要なこと
他のエンジニアが探すかもしれない内容を書いておく
1回もしくは何回も確認・説明されることがある内容はコメントされているかどうか
そのコメントを書くことで将来恩恵があるかどうか
見られることも更新されることもあまりないコメントは不要
同じコメントがあちこちにないか
コメントが重複していないか
コメントの書き方のフォーマットが決まっているか
冗長にかかれていないか
熟練者を苛立たせないか
何から何まで詳細に書いていないか
要点は書かれており、非熟練者でも理解できるか
簡潔に短く、明確に書かれているか
ライブラリ等にして公開する可能性があるものは公開してよい内容のコメントかどうか
スピード
思考が整理整頓されていて、ソースもきれいだから速い
スピード重視と言いつつ、汚く遅く実装しない
コンテンツ(画像・文章・動画)
問題のあるものをアップロード等できなくなっているか、もしくは自動的に削除されるか、削除依頼できるか
著作権
人種差別
男性差別
女性差別
禁止用語
デマ
嘘の情報
政治的な内容
人が傷付く内容
誤って個人情報が紛れ込んだコンテンツ
再現性
設定、バージョン、環境変数がリポジトリに含まれているか注記されているかどうか