なになれ

IT系のことを記録していきます

A Philosophy of Software Designの17章要約

本内容は「A Philosophy of Software Design」の17章を要約する記事です。

過去記事

16章の紹介

他担当の方が要約した16章の内容を引用します。

  • 16章 既存コードの修正
  • この章ではシステムが進化する過程で複雑性が忍び込まないようにする方法を説明
  • 開発者がバグフィックスを行うなど実装の変更を行う際、通常、戦略的な思考はしない
    • "私が必要とすることを実現するためにできる最小限の変更は何か?"を考え実行する
    • 大きな変更は新たなバグを引き起こすリスクが高くなることを懸念することが原因である
    • これでは戦術的なプログラミングになり、最小限の変更を行うたびに、いくつかの特殊なケースや依存関係その他の複雑な形態が生まれる
  • 理想的には、各変更を終えたときに、最初からその変更を念頭に置いて設計した場合の構造を持ったシステムになっていること
  • 既存のコードを変更した場合、その変更によって既存のコメントの一部が無効になることがある。それをふせぐいくつかの方法がある
  • 1. そのコメントが記述されているコードの近くに配置することで、開発者がコードを変更したときにそれを見ることができます
    • ドキュメントはコードを書く開発者にとって最も便利な場所に配置されるべき
      • 各コメントは、そのコメントによって参照されるすべてのコードを含む最も狭い範囲に押し込められるべき
      • たとえば、あるメソッドが3つの主要なフェーズを持つ場合、メソッドの先頭にすべてのフェーズの詳細を説明する1つのコメントを書くのは良くない
      • 各フェーズに個別のコメントを書き、そのコメントをそのフェーズのコードの最初の行のすぐ上に配置します
    • コードを修正するときによくある間違いは、ソースコードリポジトリのコミットメッセージに変更に関する詳細な情報を記載し、その後、コードにそれを文書化しないこと
      • コミットメッセージを書く際には、開発者が将来その情報を使う必要があるかどうかを自問すべき
    • 必要な場合は、その情報をコードで文書化すべき
    • 情報はコードの中に入れることです。これは、開発者が最も目にする可能性の高い場所にドキュメントを配置するという原則を表しています
    1. 重複を避ける
    2. ドキュメントが重複していると、開発者が関連するコピーをすべて見つけて更新するのが難しくなる
    3. 設計上の決定を一度だけ文書化すべき
    4. 負数の箇所が影響を受ける場合は、最もわかりやすい場所を1カ所だけ選んで、その場所に文書を配置
    5. 特定のドキュメントを開発者が見つけやすい場所に置くための「明白な」単一の場所がない場合、セクション 13.7 で説明するように designNotes ファイルを作成すべき
    6. さらに、他の場所には、中心となる場所を参照する短いコメントを追加
    7. 読者があなたのコードを理解するために必要なすべてのドキュメントを簡単に見つけられるようにすることは重要ですが、それはあなたがそのドキュメントをすべて書かなければならないということではない
  • ドキュメントを最新の状態に保つための良い方法の一つは、リビジョン管理システムに変更をコミットする前に数分かけて、そのコミットに対するすべての変更点をスキャンし、各変更点がドキュメントに適切に反映されていることを確認すること
  • ドキュメントを維持するための最後の考えとして、コメントはコードよりも高レベルで抽象的である方が維持しやすくなり、変更の頻度も低い

17章の要約

  • 17章 一貫性
  • 概要
    • 一貫性は複雑さを軽減し、動作を明確にする
    • システムが一貫していれば、見慣れた状況に基づいて行った推測は正しい
    • 一貫性があることで、開発者はより早く、より少ないミスで作業を行える
  • 一貫性の例
    • 名前
    • コーディングスタイル
    • インターフェイス
    • デザインパターン
    • Invariant(不変)
      • 構造体や変数の不変的な特性のこと
      • 例えば、テキストの行を格納するデータ構造では、各行の終端が改行文字であること
  • 一貫性の確保
    • 一貫性を維持することは、特に多くの人が長期間にわたってプロジェクトに携わる場合、困難
    • 一貫性を維持するためのヒント
      • ドキュメント
        • 目立つ場所にコーディングスタイルガイドを用意する
        • いくつかのスタイルガイドがWeb上で公開されているので、これらのうちの一つから始める
        • 局所的なルールは適切な場所にドキュメント化する
      • 実行する
      • 既存の慣習を変えない
        • より良いアイデアがあるからといって、矛盾を引き起こす理由にはならない
        • 慣習を変える場合にYESであるべき質問
          • 古い慣習を変えるべき重要な新情報があるか?
          • それは古い慣習を全て変える価値があるほど優れているか?
  • 行き過ぎた一貫性
    • 一貫性は同じようなことは同じような方法で行うだけでなく、似て非なることは異なる方法で行うべきということ
    • 異質なものを無理やり同じ手法にしようとすると複雑さを招くだけ
  • 結論
    • 一貫性を確保するには少し余分な作業が必要になるが、その投資に対するリターンはコードがより明白になること

感想

  • なんかイケテナイから書き方変えようとかあまり考えずにやってそうなので既存の慣習を変えないというのは意識すると良さそう
  • 一貫性を保つには仕組みだけではダメで、教育も必要だと改めて思った