スタイルガイドとルール
『Google のソフトウェアエンジニアリング』第8章を読んで理解した内容を、自分の言葉で書き直したもの。 本文の引用ではない。節番号は原典を引き直すときの手がかり。
用語の区別 (§8.0)
| 性質 | |
|---|---|
| ルール | 普遍的な強制力を持つ。守らなければならない |
| ガイダンス | 推奨事項とベストプラクティス。判断の助けになる |
スタイルガイドはルールの集成で、エンジニアが結果責任を負うときの最終的な典拠として機能する。
何のためにルールを設けるのか (§8.1)
目的は、良い行動を促し、悪い行動を思いとどまらせること。 ただし何が「良い」「悪い」かは組織によって違う。万人共通の選好ではない。
一貫性を最も重視する組織では、既存のパターンと相容れないものはすべて「悪い」になる。 だから順序はこうなる。
- 自分たちの組織が何に価値を置くかをまず認識する
- その価値に沿って行動を促す/抑えるためにルールとガイダンスを使う
ルールを作るときの問い (§8.2)
問うべきは「どんなルールを持つべきか」ではない。 「どんなゴールを前進させようとしているのか」。
個々のルールについては常に 「なぜそれがスタイルガイドに入るのか」 を問う。
ルールは、他のルールと同程度に有用でなければならない (§8.2.1.1)
ルールが増えるほど、ルール自体の保守が難しくコストも上がる。 だから数を絞る。
- 自明であることが期待されるルールは、意図的に載せない
- 間違えるエンジニアが1人か2人しかいないなら、 そのために新しいルールを作って全員の精神的負荷を増やすのはスケールしない
読者に向けて最適化する (§8.2.1.2)
書きやすさより読みやすさに価値を置く。 読みにくいくらいなら、入力が退屈な方がまだまし。
そのために、意図した挙動の明示的な証拠をコードの中に残すことを求める。 たとえば所有権の移転を全呼び出し箇所で明示させると、 読者は毎回すべての関数の挙動を理解しなくてよくなる。
ゴールは、関数の実装を探しに行かなくても、呼び出し箇所で何が起きているか分かること。
コメントは2種類に分けて考える。
| 種類 | 役割 |
|---|---|
| ドキュメンテーションコメント(ファイル・クラス・関数の前) | 続くコードの設計または意図を説明する |
| 実装コメント(コードの中に散らばる) | 明白でない選択が正しいことを示す、注意を向けさせる、一筋縄でいかない部分を説明する、重要部分を強調する |
基準は 「他のエンジニアが読み進めるときに探すであろう説明」 を提供すること。
一貫性を保つ (§8.2.1.3)
一貫性が効くのは、馴染みのない場所に突然入ったとき。 すぐ作業に移れる。
得られるもの。
- 熟練者が、重要な部分に的を絞って何をやっているか理解しやすくなる
- モジュール化と重複の発見が容易になる
- 均一性に依存するツールの恩恵を受けられ、保守タスクの多くを自動化できる
- プロジェクト間の流動性が上がる。 チームを移るエンジニアの立ち上がりが最短になり、 人員構成の変動に組織が伸縮して適応できるようになる
最後の点が効く理由は、人もプロジェクトも動くから。 エンジニアは離脱し、新しい人が入り、オーナーシップは移り、プロジェクトは合併も分裂もする。 一貫性は移行コストの低さを保証する手段になる。
注意を払う対象として挙がっているのは、命名規則・共通パターンの使い方・書式整形と構造。
社外の標準も見る (§8.2.1.3)
社外のコミュニティが採択した標準も考慮に入れて、外の世界と一貫させる。 長い目で見れば、広く受け入れられた標準を守った方が報われる。
誤りやすく意外な構文を避ける (§8.2.1.5)
強力な機能ほど理解が難しく、広くは使われない。 今のメンバーが理解していても、将来の保守担当者が同じ理解を持つ保証はない。
前提は「専門家だけが作業できればいい」ではなく、 全エンジニアがコードベース内で作業できること。だから簡潔で明快なコードの方を高く評価する。
現実に譲歩する (§8.2.1.6)
例外を正当化する事例には遭遇する。それでよい。
- 一貫性やリーダビリティを犠牲にしても、パフォーマンス最適化を許す方が合理的なことがある
- 自動生成コードで、プロジェクトの管轄外と通信・依存するものは明示的にルールの範囲外とする
スタイルガイドに何を入れるか (§8.2.2)
| 目的 | 内容 |
|---|---|
| 危険を避ける | どの言語機能を使い、どの構文を避けるか。使うのが難しいもの、正しく使うのが難しいものへの裁定 |
| ベストプラクティスの強制 | ソースファイルの構造など。まだ十分に理解されていない新しい言語機能への制限も含む |
| 一貫性の組み込み | 技術的優劣に差がない選択肢について、1つに決める |
新しい言語機能を制限する狙いは、全員が学習途上のあいだ、落とし穴の周りに先回りして柵を立てること。 事例が十分に集まってから、良いプラクティスを一般化して悪いものを外す。
一貫性の項目については割り切りが明快で、 明確で計測可能な技術的利点の差がないなら、1つ選んで終わりのない議論から抜け、先に進む。
入れないもの (§8.2.2.4)
コードベースの健全性に最も大きな影響を持つものに専念するので、入っていないものは多い。
明文化されていないベストプラクティスは確実に存在するし、その中には根本的なものも多い。 スタイルガイドは新人を達人レベルまで連れて行く役目は果たさない。 前提としていることがあり、それは意図的。
ルールを変える (§8.3)
- ルール更新のプロセス自体を用意する
- 変更の提案は、まず既存の問題を特定し、その修正方法として提示する
- 変更が必要だと気づくのに最良の立場にいるのは、そのルールに統制されてコードを書いているコミュニティ
誰が決めるか (§8.3.2)
言語ごとに、長年の経験を持つ専門家グループがスタイルガイドのオーナー兼意思決定者として任命される。
変更は個人の好みではなくトレードオフの判断。 「自分がこうあるべきと思うから」という性質の意思決定ではないので、 決定は投票ではなく全会一致で行われる。
ガイダンスと入門書 (§8.3.4)
ガイダンスは、組織のエンジニアリング経験の集合知を文書化したもの。 対象になりやすいのは、同じ間違いが頻繁に目撃されているものと、 馴染みがなくて混乱しやすい新しいもの。
「今週のヒント」形式が社内で成功したという話が具体的で、特徴はこう。
狭い範囲に的を絞る
短く、読むのに数分しかかからない
実際に遭遇した問題から生まれている
スタイルガイドが扱っていない現実のプログラミングの問題に対処する
広範かつ直接的に適用できる
結果として、コードレビューと技術的議論の最中に頻繁に引用されるようになった。
ルールを適用する (§8.5)
ルールの遵守はツールで自動化する方を強く推す。
- 遵守のコストを下げるほど、エンジニアが快く守り続ける可能性が上がる
- 解釈のばらつきが最小化される。 人間は自分のバイアスで色づけされた観点を通して見るので、 解釈を各エンジニアに任せない
ただし例外がある。ツールに落とし込むのが複雑で高コストなルールは、人間に任せた方がよいことが多い。
フォーマッターの効用として挙げられているのは、gofmt があるおかげで
gofix の生成する差分に重要な変更だけが含まれるようになったという例。