ディレクトリ
文書の作業多くの開発者が、あるコーディングと単体テストが完了すると、開発プロセスの最後まで延期する準備されます。これは、低品質のドキュメントを作成するための最も確実な方法の一つです。コメントの書き込みを開始するための最良の時間は、コードを書くときに、あるプロセス、です。まず、文書書かれたコメントは、設計プロセスの一部となります。これは、より良いドキュメントを生成するだけでなく、よりよい設計、およびドキュメントをより楽しく執筆のプロセスを生成しないだけ。
15.1遅延コメントが悪いコメントしました
私はほとんどすべての開発者がコメントを書く時間を遅らせている会いました。ドキュメント以前の書き込みではない理由を尋ねられたとき、彼らはコードがまだ変化していると述べました。より良いコードが安定するまで待つように、彼らは長い文書を書かれている場合そして、彼らは時にコードの変更、彼らは文書を書き換える必要があります、と言います。しかし、私は彼らがクーリー作品として文書を考えていることを、別の理由がある疑いがあるため、彼らは可能な限り遅らせます。
残念ながら、このアプローチは、いくつかの負の影響を持っています。まず、遅延が通常の文書が文書を書く必要がないことを意味します。あなたが遅延を開始すると、それは簡単に、さらに遅延がほとんどであり、数週間、すべての後に、コードがより安定になります。コードはドキュメントを作成する作業も魅力的ではない、非常に困難になっていることを意味し、多くは、すでにそこにある、落ち着いまで待ちます。数日間停止する決して権利時間は、すべてのコメントは補うために不足している、そしてプロジェクトを考えるのは簡単ですバグ修正や新機能は次の書き込みに、前進するための最良のものです。これは、より多くの文書化されていないコードを作成します。
あなたが書き込みノート（自分自身を欺くしないでください：あなたがいない場合があります）に戻ります自己規律を持っている場合でも、コメントは良いことではないだろう。プロセスのこの時点で、あなたは精神で残っています。あなたの心には、このコードは完了した。あなたは、次のプロジェクトを開始することを熱望しています。あなたは、そのコメントを書くには正しいことだけど、それは何の楽しみません。あなたは、できるだけ早く嵐を乗り切るしたいです。そのため、あなたはすぐにそれが満足に見えるように十分なコメントを追加し、コードを閲覧することができます。あなたは、設計プロセスのぼやけ思い出になるようにこれまでのところ、あなたは、いくつかの時間のためのデザインコードを持っていません。あなたはノート、注釈ので、繰り返しコードを書く時にコードを見てください。あなたは、コードのデザインが明らかにされていません再構築しようとしている場合でも、あなたは覚えていないものがあるでしょう。したがって、これらのコメントは、彼らが説明されなければならない最も重要なことのいくつかを無視します。
15.2コメントを書きます
私はコメント、私が最初に書いたコメントを書くために別の方法を使用しました。
- 新しいクラスのために、私は最初の書き込みのインターフェースコメントしたいと思います。
- 次は、私が最も重要な公共などの注意事項と署名インタフェースを記述しますが、メソッド本体は空です。
- 私はこれらのコメントのいくつかの繰り返し、正しい日付までの感情の基本的な構造をしました。
- この時点で、私が最も重要なクラスのインスタンス変数のクラスのための文やメモを書きました。
- 最後に、私は必要に応じて実装コメントを追加し、メソッドの本体に記入します。
- 調製方法本体では、私は通常、追加のメソッドやインスタンス変数が必要であることを見つけます。それぞれの新しい方法のために、私は、メソッド本体のライト・インタフェースの前にコメントを持って、変数の宣言を書きながら、インスタンス変数のために、私はコメントを記入してください。
コードが完了したら、コメントも完成します。不文のないバックログをコメントはありません。
最初の注釈方法は、3つの利点があります。
- まず、それがよりよいノートを生成します。あなたがデザイン部門でコメントを書いた場合、それがレコードに簡単ですので、その後、主要な設計上の問題は、あなたの心の中で出てきます。
- あなたが達成気を取られることなく、抽象およびインタフェースのメソッドに集中できるよう、各インタフェースのノートの本体の前に準備するための最良の方法。
- コーディングとテストプロセスでは、あなたは気づくでしょうし、コメントに問題を修正します。したがって、開発の過程で継続的な改善をコメント。
15.3ノート設計ツールであります
第二の利点（そして最も重要なA給付）の開始時にコメントを書くシステム設計を改善することです。ノートは完全に抽象的、抽象化をキャプチャする唯一の方法は良いシステム設計のための良い基礎です提供します。あなたが先頭にコメントの抽象的な記述を書く場合は、実装コードを書く前にそれらをチェックし、調整することができます。良いコメントを書き込むには、変数やコードの一部の性質を特定する必要があります。この事の最も重要な側面は何ですか？これを行うには、設計プロセスの初期には非常に重要であり、そうでなければ、単にコードを解読します。
ノート炭鉱複雑でカナリアのようなものです。メソッドや変数は、長いコメントを取る場合、これはあなたが良い抽象を持っていないという警告です。最高のクラスは非常にシンプルなインターフェイスを持っていますが、強力なを実現：覚えて、第4章では、クラスは、深さでなければなりません。インターフェースの複雑さを決定する最良の方法は、その注釈に応じて記載されています。インタフェースのメソッドは非常にシンプルで非常に短いこの方法を使用するために必要なすべての情報を、提供する場合の注意事項は、このメソッドはシンプルなインターフェイスを持っていることを示しています。そこには長いされていないと、複雑な注釈が完全にメソッドを記述することができない場合は逆に、この方法は、複雑なインターフェースを持っています。あなたは、このアプローチの深さを理解するために注釈を付けるとインタフェースメソッドを比較して実装することができます：インタフェース実装コメントのすべての主要な特徴が説明されなければならない場合は、この方法は、表面的です。同じ考え方も変数に適用されます：あなたは完全に変数を記述するために長いコメントを取る場合、これはあなたが正しい変数の分解を選択しないことが危険な兆候です。一般的には、あなたが問題を見つけて修正することができますので、書き込みコメントの動作は、あなたが可能な限り早い段階として、あなたの設計上の決定を評価することができます。
危険信号：筆舌に尽くし難いです
メモは、メソッドや変数はシンプルかつ完全でなければならない説明します。あなたはそれが困難なコメントを書き込むことが判明した場合、それはあなたが問題になることが説明されているものの設計を示しています。
もちろん、コメントは唯一の完全かつ明確な条件が複雑の良い表示することができます。あなたがインターフェイスメソッドを記述する場合のコメントは、メソッドの呼び出しを提供するために必要なすべての情報はなかった、またはコメントが非常に不明瞭と理解するのが難しい場合、コメントは方法の深さの良い指標ではありませんです。
15.4早期コメントは非常に興味深いです
すぐに3番目と最後の恩恵のように書かれたコメントは、注釈の書き込みは、もっと面白いことができるということです。私にとっては、プログラムの中で最も興味深い部分は、新しいクラスの設計の初期段階の一つであり、この段階で、私は抽象的構造を豊かにしたいと思います。私のコメントのほとんどは、これらのコメントは、私は私のデザインを記録し、意思決定の質をテストする方法です、この段階で書かれています。私はフルに表現し、最小限の言語でクリアすることができ、デザインを探しています。もっと簡単なコメントが、私はそう簡単なコメントは私の誇りで見つけ、より良い自分のデザインを感じました。あなたが戦略的にあなたの主な目標ではなく、単に仕事にコードを書くよりも、素晴らしいデザインでプログラムされている場合、これはあなたが最適な設計を特定の方法であるので、書き込みのコメントは、興味深いものになるはずです。
それ以前の15.5コメントはコストがかかりますか？
さて、それはコードの開発やコメントを再処理してコストを回避することを遅延コメントの理由を再検討してみましょう。簡単な概算はそれがはるかに貯蓄を持っていなかったことを示します。まず、コードと時間のコメントを修正することを含む、それが取る入力コードとコメントを使用して開発時間を推定し、これは、総開発時間の10％を超えることはほとんどありません。コードの総行の半分があなたのコメントであっても、書かれたコメントは、あなたの全体の開発時間の5％を占有されることはありません。最後までコメントは、それのほんの一部ではなく、多くのことを保存します。
まず、あなたは、コードの抽象を書き始める前に、より安定になることを意味するとのコメントを書かれて。これは、エンコード時の時間を節約することがあります。逆に、あなたは抽象コードは、最初のコメントが多くのコードの修正を必要とよりも、この方法を開発した可能性があるとして、あなたは、最初のコードを記述します。アカウントにこれらすべての要因を取るときは、最初の書かれたコメントは速いかもしれません。
15.6まとめ
コメントを書くためにしようとしていない場合は、それを試してみてください。これまでの習慣に従います。そして、それは、コメントの質をどのように影響するかを検討し、全体的な設計品質とソフトウェア開発をお楽しみください。あなたがしようといくつかの時間の後、あなたの経験は、私と一致した場合、私に知らせて、そしてそれはなぜ。