コードドキュメントの生産性の向上/低下に関する研究
多くの検索の後、私はソフトウェア開発の世界で知られていると思われるものに関する基本的な質問に答えることができませんでした。
何IS既知：
適切なコードドキュメント（Doxygenタグ、Javadoc、または単に大量のコメント）に厳格なポリシーを適用すると、コードの開発に必要な時間が長くなります。
だが：
完全なドキュメント（またはAPI）があると、機能を追加したり、将来的にバグを修正したりするときに、新しい開発者や経験豊富な開発者の生産性が向上します（想定されます）。
質問：
このようなドキュメントを保証するために必要な追加の開発時間は、（厳密に経済的な意味で）将来の生産性の向上によって相殺されますか？
私は、事例研究、または引き出された結論を裏付ける客観的な証拠をもたらすことができる答えを探しています。
前もって感謝します！
「活版印刷のスタイルは見た目以上のものです」という記事はかなり古いですが、非常に興味深いものです： http://portal.acm.org/citation.cfm?id=78611 。
古いので、最近可能になるすべての凝ったものが含まれているわけではありませんが、コードのドキュメントが重要であることを明確に示しています。
私のようにACMデジタルライブラリにアクセスできない人のために、彼らは2つのプログラマーグループを作成し、同じコードを研究用に提供しました。グループAは通常のコメント付きのコードだけを受け取り、グループBは目次、相互参照、および1990年に可能だったすべての優れた点を含むきれいに印刷されたリストを受け取りました。
次に、2つのグループに、コードに対して特定のタスクを実行するように依頼し（たとえば、関数を拡張する、バグを見つけるなど）、回答の速度と品質の観点からスコアを付けました。
グループのバランスをとるために、彼らには同数のエキスパートプログラマーとジュニアプログラマーがいました。
さて、グループB（かなり印刷されたリストを持つもの）は、多くのテストでグループAよりも一貫してスコアが高いことがわかりました。そして、特定のケースでは、グループAの最も専門的なものだけがグループBのジュニアプログラマーを超えることができました。
記事にはもっと書かれていますが、これは私が記憶から思い出すことができるものです（私はまだどこかに印刷された記事を持っているはずです）。
少なくとも私にとっては、読み取り可能なコードは、不十分に記述されたコードを補うためだけに役立つドキュメントよりもはるかに価値があることは明らかです。私は、コード内のコメントを、コードを書き直してコメントを削除し、より自明にすることができるかどうかを確認するための課題と見なす傾向があります。
常識を除いて、確かな証拠でそれを裏付けることはできません。
引用する研究はありませんが、簡単なルールがあります。2週間後にコードに戻って、自分が何をしたのかすぐに理解できない場合は、コメントを追加するか、簡略化する必要があります。 。
確かに、howコードが機能することは、コード自体によって文書化する必要があります。しかし、注意深く簡潔に説明するコメントを書くのに費やした時間なぜあなたのコードは、たとえあなたがコードを維持している唯一の人であったとしても、長期的にはほぼ確実にそれ自体が報われる方法で書かれています。
ソフトウェアの寿命は主にメンテナンス段階で費やされるため、開発者がより早くスピードを上げるのに役立つため、プログラマーが何が起こっているのかを理解するのに役立つものは、ほぼ確実に経済的利益をもたらします。
コードにAPIを文書化するのが少し簡単ではないAPIでは、ほとんど役に立ちません。これは、APIの能力が、（個々のメソッド/オブジェクトがどのように機能するかではなく）ユニット全体としてどのように連携するかに由来するためです。
したがって、実際のドキュメントよりも役立つのは、APIの予想される使用パターンを説明するクックブックのようなドキュメントと、いくつかの明らかな状況（APIの大部分（100％ではない）を使用する）を解決する方法の例です。
与えられた方法が、おそらくまだ発明されていないツールがなければ、ドキュメントを書くことをrequireに主観的すぎるかどうかの決定。
「すべてのパブリックメソッド」や特定のパッケージ内のすべてのクラスなど、最善の方法は役立つ場合がありますが、特定の使用例を超えて推奨するにはラフすぎます。
私の提案：開発者に、文書化するのに重要なメソッド（公式または非公式のAPI、一般的に使用されるスタブメソッド、複雑または難解なメソッド）を特定し、それらを管理させる方法を教えてください。
（密接に関連している： コーディング標準にあまりにも多くの均一性がある可能性がありますか？ ）
引用する研究がないことをお詫びしますが、これは、それを測定しようとすると結果に大きな影響を与え、一般的な結論を引き出すことができないという問題であると思われます。
この点で、パブリックAPIから「通常の」コードを分離する必要があると思います。通常のコードについては、他のほとんどの回答者に強く同意するようになりましたコードは自己文書化され、散文のように読まれる必要があります。私のコードがそのようでない場合、それは通常私のせいですので、文書化するのではなく、リファクタリングする必要があります。 一度に1つのことだけを実行し、単一レベルの抽象化に取り組み、正確でわかりやすい名前を付けるという小さな方法は、これを達成するための優れた方法になります。
コメントの問題は、コメントが腐敗することです。コメントを追加するとすぐに、付随するコードに依存しない生活が始まります。 コードを変更する次の開発者が関連するコメントも忠実に更新する可能性はどのくらいありますか？私の経験では、ゼロに近いです。いくつかの変更を加えた後の最終結果は、コメントが人々を助けるのではなく、人々を困惑させたり誤解させたりすることです。
可能性例外は、パフォーマンスが最適化されたコード、または特定のアルゴリズムの使用です。この場合、コードがどのように見えるのか、アルゴリズムへの参照などを説明するコメントを追加すると便利です。
このトピックに関する重要な作業は クリーンコード です。
OTOH パブリックAPIはJavadocで十分に文書化されている必要があります。非常に多様なスキルと仮定を持つ無数の見知らぬ人によって使用される可能性があるため、可能な限りシンプルで明確に使用できるように予防策を講じる必要があります。それは依然として主に適切なAPI設計の問題ですが、ドキュメント化にも重要な役割があります。
問題は、コードを文書化することで時間を節約できるかどうかです。それ以降のすべての開発者は、何が行われているのかを理解しようとする必要があります。コードが何をするのかについて誰も質問せずにコードレビューを通過する場合は、おそらく良好な状態です。入力についての仮定を説明するのはそれほど難しくありません。メソッドが整数オブジェクトを受け取り、文字列オブジェクトを返すとしましょう。 intをnullにすることはできますか？最小/最大値（integer.MinValue/MaxValue以外）はありますか？空の文字列またはnullを返すことはできますか？例外をスローしますか？もちろん、誰でも検査でこれらを見つけることができますが、他の開発者があなたのコードを十分に使用する場合は、数分ごとに節約することは時間の価値があります。また、テスターはコードを確認するためのテストを作成することができます。
私のキャリアの中で、さまざまなレベルのドキュメントと品質のコードを見てきました（ドキュメントと品質は正統的な懸念事項であることに注意してください）。ドキュメントに費やした時間を品質の向上に使用したいと思います。単純なケースの場合、関数を調べてドキュメントコメントを生成できるGhostDocのようなツールがあります。 GhostDocが関数の機能を示す意味のあるコメントを生成できる場合は、適切な名前の関数を使用するという目標を明らかに達成しています。
多くの場合、GhostDocは、関数が実際に何をするのかを教え始めることすらできません。あなたの時間は、その問題に対処し、（多分）ghostdocを使用してコードを自動生成することに費やしたほうがよいでしょう。
詳細については、Bob Martinの Clean Code および [〜＃〜] ppp [〜＃〜] を参照してください。
これは確かに興味深いトピックです。開発者がドキュメントの作成や保守に時間を費やすべきかどうかについては常に議論がありますが、実際には、開発者が自分よりもコードに再度アクセスするときに、コードを適切に記述し、非常に適切にコメントする必要があります。コードがどのように書かれたか、さらに新しいチームメンバーがチームに加わった場合、コードが明確に文書化されているため、コードの機能と動作を理解するよりも、そもそも何をすべきかを考えるのに時間を費やす必要はありません。
したがって、コードは非常によくコメントされている必要があり、外部ドキュメントを必要としない自己文書化コードである必要があります。