ディレクトリ
第1章では、ソフトウェアの開発は、反復と増分である方法を説明します。進化の段階の一連の大規模なソフトウェアシステムの開発は、各ステージは、新しい機能を追加し、既存のモジュールを変更します。この設計では、システムが進化していることを意味します。これは、適切に設計されたシステムの最初に考えることはできません。成熟したシステム設計ではなく、オリジナルのコンセプトより、システム開発プロセスの変化に、より依存しています。この章で説明するが、どのようにシステムが増加の開発と複雑さを防ぐために、最初の数章は、初期の設計と実装工程における押出複雑さはどのように説明します。
16.1は、戦略的な維持します
第3章では、戦術的および戦略的なプログラミングプログラミングの違いを説明します。戦術にプログラミング、主な目標は何かがさらに複雑で、この結果があっても、すぐに作業を取得することで、戦略的計画で、最も重要な目標は、偉大を生成することですシステムの設計。戦術はすぐに混乱設計システムにつながります。あなたは簡単に維持し、システムを拡張したい場合は、「仕事」は十分に高い標準ではありません。あなたは、デザインと戦略的思考を優先しなければなりません。既存のコードを変更する場合、この考え方にも適用されます。
開発者は、深いメイクに、既存のコードに行くとき、彼らは通常、戦略的に考えていない、のような残念ながら、このようなバグ修正や新機能として変化します。典型的な態度は、「私は私のニーズを満たすために何ができるか、最小の変更？ある」「彼らは、コードを変更するのは好きではないので、時々 、開発者がそれを行う、彼らは大きなを導入する大きな変化をもたらす恐れ新しいバグのリスクが。しかし、これは戦術的な計画につながっている。これらの最小限の変更のそれぞれは、いくつかの特別な場合、依存関係や複雑さの他の形態で導入されました。その結果、システムの設計が悪くなり、問題システムの累積の進化のすべてのステップ。
あなたはクリーンなシステム設計を維持したい場合は、既存のコードを変更するとき、あなたは戦略的なアプローチを取る必要があります。あなたはそれぞれの変更を完了すると理想的には、システムは、あなたが最初の構造を持っているから念頭に置いて設計している場合があります。この目標を達成するには、クイックフィックスの誘惑に抵抗しなければなりません。代わりに、現在のシステムは依然として必要に応じて最高のデザイン、変更であるかどうかを検討します。ない場合は、システムの再構築は最高のデザインを取得します。システム設計は、この方法により、すべての変更を改善することができます。
この例は、15ページの説明投資の考え方です：あなたが再構築し、システム設計を改善するために少し余分な時間を投資した場合、あなたはよりコンパクトなシステムを取得します。これは、開発をスピードアップし、あなたは復興努力への投資を回復します。あなたの特定の変更が再構成を必要としない場合でも、あなたはまた、コード内の修正設計上の欠陥に目を向ける必要があります。任意のコードが変わるたびに、我々は、プロセス内の1時を向上させるために、少なくとも、システム設計を改善しようとしなければなりません。あなたはデザインが良く行わない場合、あなたはそれを悪化させる可能性があります。
我々は、商用ソフトウェアの開発と、時には競合する第3章、実際の投資の考え方で説明したように。悪い素早く修理とはわずか2時間を必要としながら、システムを再構築する「正しい方法」は、3ヶ月を必要とする場合は、特に緊急あなたの勤務時間中に、迅速かつ悪い方法を取らなければならないことがありケース。または、システムの再構築が非互換になります場合は、これチームや他の多くの人々に影響を与え、その後、再構成は実用的ではないかもしれません。
ただし、可能な限りこれらの妥協を耐えなければなりません。多分3ヶ月の再建など、単純なように、方法があるが、することができ、「これは私がクリーンなシステム設計を作成するためにできる最善である、私の現在の制限を考慮すると？」：自問してみてください数日以内に完了するために？あなたが大規模な再建の費用を負担することができない場合は、あなたは現在の締め切り後に再構築を行いますので、あなたの上司は、あなたに割り当てられた時間を与えることができます。各組織は、クリーンアップと再構築のための仕事のすべてにその計画の小さな部分を開発する必要があり、作業は長期的に価値があります。
16.2メンテナンス注：コードの近くにコメントを入れて
既存のコードを変更すると、それはいくつかの既存の注釈失敗することがあります。コードを変更する場合は、正確ではもはやコメントになりますこれ、メモを更新することを忘れないことは容易です。不正確なコメントは、あまりにも多くのコメントは、読者がすべてのコメントを疑うに開始されます場合は、読者が不満を感じさせます。幸いなことに、大規模な努力にコメントせずに更新することができ、ほとんどのルールやガイドラインに。このセクションの次のセクションと特定の技術の数を作りました。
コメントは、コードを変更すると、開発者はそれらを見ることができるように、彼らは記述するコードの近くにそれらを配置するように更新されていることを確認するための最良の方法。遠くに関連するコード、あまり正しい更新の可能性からのコメント。例えば、インタフェースメソッドの最良の位置は、メソッド本体に次のコードファイルを、注釈されています。開発者は、インタフェースのコメントを参照し、必要に応じて更新することができように、方法への変更は、このコードを伴います。
例えばCやC ++言語に依存しないコードおよびヘッダファイルを持つために、別の方法はさておき.hファイル注釈メソッド宣言をインタフェースすることです。メソッド本体を変更する開発者は、これらのノートは表示されませんし、ファイルを開いて、それらを更新するために、さまざまな注釈のインタフェースを見つけるために、余分な作業を必要とし、しかし、これはコードから長い道のりがあります。一部の人々は、ユーザーがコードファイルを見てなくても、抽象を使用する方法を学ぶことができるように、コメントはインタフェースヘッダファイルに置かれるべきだと思うことがあります。ただし、ユーザーがコードやヘッダファイルを読み込む必要はありません。彼らは、Doxygenのか、Javadocドキュメントなどのコンパイルツールから情報を取得する必要があります。加えて、多くのIDEは、メソッド名を入力するとき、そのような文書表示方法として、文書を抽出するためにユーザに表示されます。このようなツールのために、ドキュメントは書き込みコードに開発者に最も便利な場所に配置する必要があります。
実装コメントの製造において、すべてのコメントは、全体的な処理方法の上に配置されていません。それらは展開、各注釈は、それが参照するすべてのコードを含む狭い範囲に押し下げ。この方法は、三つの主要な段階を持っている場合たとえば、詳細に説明した方法の全てのステージの上部にあるノートを書いていません。その代わりに、単一のコメントの調製、及びコメントの各段階のためのコードの最初の行のステージ上に配置されます。一方、全体的な戦略を説明するコメントをトッピング達成する方法は、次のようにも役立ちます。
// We proceed in three phases:
// Phase 1: Find feasible candidates
// Phase 2: Assign each candidate a score
// Phase 3: Choose the best, and remove it16.3注釈ではなく、コミットログよりも、コードに属し
あなたは、コードを変更する場合、一般的な間違いではなく、コードでそれを記録するよりも、コミットメッセージのソースコードリポジトリの変更に関するより多くの情報を置くことです。スキャンすることで店舗を閲覧することは可能ですが、将来的にメッセージログをコミットするが、これらの開発者の情報ニーズを使用すると、リポジトリのログをスキャンしたいと考える可能性が低いです。彼らは正しいログメッセージを見つけるためにスキャンログを行う場合であっても非常に面倒になります。
コミットメッセージを書き込むとき、将来の開発者が情報を使用する必要があるかどうかを自問してみてください。その場合は、コード内の情報を記録します。メッセージをコミット原因コードの変更の微妙な問題を説明する例です。開発者は、後に発生した変更を元に戻すが、彼らは気付いていないかもしれので、このコードのレコードが存在しない場合はエラーを再作成しました。あなたはまた、メッセージにこの情報の提出のコピーを含める場合、それは素晴らしいことだが、最も重要なことは、あなたのコードでそれを取得することです。この番組ローカル開発者のドキュメントが最も可能性が高いの原則を参照してくださいになっているが、その場所にあまりログインしていないコミット。
16.4 Reserved注：重複を避けるために
第二の技術のコメント日付は、重複を避けるためです。文書が重複している場合は、開発者がすべてのコピーを見つけて更新することは困難です。その代わり、唯一のすべての設計上の決定後に録音してみてください。特定の意思決定コードの影響を受け、複数の場所がある場合は、それぞれの場所で重複していない文書を行います。代わりに、文書を置くための最も明白な場所を見つけます。たとえば、あなたが変数に関連付けられている複雑な挙動があると、それはいくつかの異なる場所で使用される変数に影響を与えます。あなたは、次の変数宣言にコメントで行動を記録することができます。開発者は、難易度、この変数を使用してコードを理解している場合は、これは非常に自然な場所です。
特定の文書を入れてない「明白な」場所がない場合、開発者はそれを見つけることができ、セクション13.7で説明したように、その後、designNotesファイルを作成します。それとも、そこにドキュメントを置くのに最適な場所を選択してください。「コードの以下の説明を理解するために、XYZビューのコメント。」あなたはを参照している場合、メインコメントが移動されたり時代遅れになる削除済みとして、この矛盾は、自己次のようになります。また、他の場所で短いコメントを基準中心位置を追加メタファーは、開発者が指定地域内のコメントを見つけることができませんので、彼らは何が起こったのか、コメントを見つけるために、リビジョンコントロール履歴を使用して、参照を更新することができます。文書が複製され、そしていくつかのコピーが更新されていない場合は逆に、その後、開発者は、彼らが古い情報を使用している知ることができません。
既に情報がプログラムの外のどこかに記録されている場合は、プログラム内ではない重複レコードを行い、外部ドキュメントを参照するだけ。あなたが実装HTTPプロトコルというクラスを記述する場合たとえば、あなたは、HTTPプロトコルがコードに記述されている必要はありません。インターネットは、この文書に多くの情報源を持っている、ちょうどあなたのコードに簡単なコメントを追加し、ソースとしてそのURLを追加します。別の例は、すでにユーザーマニュアル機能に記録されています。各コマンドのメソッドを実装するための責任がある、あなたはsetコマンドを達成するためのプログラムを書いているとしましょう。これらのコマンドは、ユーザーマニュアルに記載されている場合は、コード内の情報を繰り返す必要はありません。代わりに、各コマンド注釈法の簡単な説明を含むインタフェースで：
// Implements the Foo command; see the user manual for details.
重要なのは、読者が簡単にあなたのコードを理解するために必要なすべての文書を見つけることができるということですが、それはあなたがすべての文書を記述する必要が意味するものではありません。
別のモジュールでモジュールの設計上の決定を再録音しないでください。例えば、方法までで呼ばれているものの方法で起こった説明するために、コメントで呼び出されません。読者が知りたい場合は、インタフェースの注釈方法をご覧ください。グッド開発ツールは、多くの場合、自動的にこの情報を提供しているあなたはそれ以上の方法やホバーの名前を選択した場合、例えば、それは方法のインタフェース注釈が表示されます。開発者は右の文書を見つけることが、文書を複製しないため簡単にそれを作るようにしてください。
16.5メンテナンス注：違いをチェック
変更はリビジョン管理システムにコミットされる前に確認してくださいドキュメントが最新の状態に保たそれぞれの変更が適切に文書に反映されることを保証するために、すべての変更を送信するためにスキャンするために数分かかり、良いアイデアです。これらのスキャンは、修理やTODO項目に失敗し、システム内のフィールド希望的観測デバッグコードを残して、他のいくつかの問題を事前にコミット検出します。
注釈の16.6より高いレベルを維持しやすいです
ドキュメントのメンテナンスにはA、最終的な思考：コメントはコードよりも進んでいる場合は、より抽象的なので、彼らは保守が容易です。彼らは、コードに若干の変更によって影響を受けないように、これらのコメントは、コードの内容を反映するものではありません。唯一の変更は、これらのコメントの全体的な動作に影響を与えます。もちろん、第13章で説明したように、いくつかのコメントは、詳細で正確な必要です。しかし、一般に、最も有用なコメントは、（彼らは単にコードを繰り返さない）を維持するのが最も簡単です。