すべてを文書化するべきですか、それともほとんど文書化すべきですか？

フィールドのgetterとsetterの「JavaBeanの」構文を含む文書すべてに論争の対象のビットようだ：人々は言うその不必要に長いと繰り返し破断DRY（自分を繰り返さない）、命名規則を説明しなければならないことのすべてを、また、コード/ドキュメントが乱雑になります。時にはそれらの引数が機能します。しかし、他の場合には、これで終わります：

上記は、これらの原則に大胆に従っているオープンソースプロジェクトに共通しています。完全に役に立たないドキュメントが残っています。それは、下で何が起こっているのか、考えられる効果、または期待値が何であるのかについては何も説明していません（nullになるか、nullにならないのかわかりません。Javadocは教えてくれません）。

それでは、いつ文書化する必要がありますか？ときどきコードが乱雑になっても、すべてを文書化しますか？それとも、私の目には「明らか」だから何も文書化しませんか？

文書化する意味のあるすべてを文書化します。

理想的な世界では、はい、すべてを文書化するでしょう。しかし、地球上では、締め切り、機能の削減、家族や友人が訪れる、休暇を取る、1日で24時間、1年で365日しかありません。すべてを文書化するのに十分な時間がありません。最適な方法で、できることはすべて文書化してください（完了しません）が、費用を最大限に活用するには次のようにします。

• 文書化が必要になる可能性が低くなるように、コードを読み取り可能にし、メソッドシグネチャをできるだけ明確にします。
• 最も不明瞭なものを最初に文書化します。物事をドアから外すためにあなたがしなければならなかった狂ったハックを文書化することによって、他の人を助けてください。
• 何の前に理由を文書化します-「残高が0未満で評価が1未満の顧客レコードを反復処理し、それらをexemptCustomersリストに追加する」など、何が行われるかをコメントしないでください。ドキュメント、なぜあなたはこれらの顧客は、負のバランスと低評価を持っているのでように」、彼らは私たちがお金を失うことを引き起こしている、平易な英語（またはあなたのチームの言語）のリストにそれらを追加しているが、これをチェックアウトすることができることからそれらを除外します。

何も説明する必要を感じずに、他の誰かがそれを読むのを見ることができるまで文書化を続けてください。

先週、The Daily WTFでドキュメントに関する素晴らしい記事がありました。私はそれがすべてを言っていると思うので、私はただリンクを残します：

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

基本的に、役に立たない場合は何かを文書化するべきではなく（一部の文書は引き出しの中に腐敗するだけで残っている）、プロジェクトの特定の部分を理解するために必要な最小限の情報を文書化するべきではないということです。ドキュメントが多すぎると、読者が混乱するだけです。

本当にそれを読む聴衆にとってコードがどれだけ読みやすいかに依存します。誰があなたのコードを読んでいるのかを把握し、そのプロフィールに合う人にあなたのコードを読んでもらいます。

もう1つの方法は、1週間後に独自のコードをレビューし、まだ何をしたかを理解しているかどうかを確認し、理解していない場合は文書化し、2週間ほどでコードをレビューすることです。

明確で詳細なドキュメントに感謝しますが、自己ドキュメント化コードのようなものはありません。だから、一番下の行は（私にとって）です：

（ソースコード）のドキュメントを非常に疑ってください。コードを改善して冗長化を試みますが、必要に応じて明確かつ完全に文書化することをためらわないでください。

もちろん、特定の状況下では、「コードが何をしているのかを説明する」以外の理由でドキュメントが必要になる場合があります（例：大規模なチームベース、組織標準など）。

ドキュメンテーションに関する私の提案は、コードに何か奇抜なものがある場合、それは最新の状態に保つべきドキュメントに属しているということです。多くの解釈が必要な空想は、私の心では、注意すべき副作用があるかもしれない特定の方法で何かが行われる場所です。すべての子孫でテストを実行します。何かが特定の方法で行われた理由を明確にすることは、何かを使用する正当な理由があったかどうかを知る良い方法です。

簡単に言えば、現在の開発者と将来のメンテナーを支援するドキュメントがあります。

その単純な格言を覚えているなら、ドキュメントのレベルは自己定義的でなければなりません。

ドキュメンテーションは、ドキュメンテーションのために時間の無駄です...しかし、5年後にコードをリバースエンジニアリングしなければならない人よりも、今日何をしているのかを説明する方が役立ちます。

個人的には、すべてを文書化することを検討するアプローチを採用しています。つまり、コーディング中に、ドキュメントが価値を高めるかどうかをあらゆる点で検討します。ほとんどの場合、元の質問で言及された種類の制約とドメイン知識については、答えはイエスです。例えば、ヌル能力、固有の制約、より広い領域のフィールドの解釈。

重複を避けるため、この種の情報を使用して主要なAPIクラスを頻繁に文書化する傾向があります。次に、非自明または一貫性のない動作がある実装と内部のみを文書化します。APIのユーザーが最も多くのヘルプとドキュメントを必要とするので、これがうまく機能することがわかります。

また、ゲッターのみを文書化する傾向があります。セッター、フィールド定義、コンストラクターパラメーターにドキュメントを複製しません。これらの場所でのデフォルトなどの非自明な動作のみを文書化します。ゲッターのドキュメントから推測できる動作は文書化されていません。たとえば、ゲッターがnullを返さないと文書化されている場合、デフォルトがない限り、nullをセッターに渡すことができないことを文書化しません。

何人かの人々は、ドキュメンテーションを考慮したが、それが不必要であると気付いた場所に空のコメントを追加することによって、「ドキュメンテーションを考慮する」行為をマークしたい。コードを混乱させて邪魔するだけなので、私はこのプラクティスが好きではありません。