コード文書の生産性の向上/損失に関する研究

多くの検索を行った後、ソフトウェア開発の世界で知られていると思われるものに関する基本的な質問に答えることができませんでした。

知られていること：

適切なコードドキュメント（Doxygenタグ、Javadoc、または単なるコメントの豊富さ）に厳格なポリシーを適用すると、コードの開発に必要な時間がオーバーヘッドになります。

だが：

徹底的なドキュメント（またはAPI）を持っていると、新しい開発者やベテランの開発者が機能を追加したり、バグを修正したりするときに生産性が向上（想定）します。

質問：

そのようなドキュメントを保証するために必要な追加の開発時間は、将来の生産性の向上によって相殺されますか（厳密に経済的な意味で）？

ケーススタディ、または導き出される結論を裏付ける客観的な証拠をもたらすことができる答えを探しています。

前もって感謝します！

記事「表記上のスタイルがより化粧品よりは」かなり古いですが、それは非常に興味深いです：http://portal.acm.org/citation.cfm?id=78611。

古いため、最近可能となるすべての豪華なものが含まれているわけではありませんが、コードのドキュメントが重要であることを明確に示しています。

私のように、ACMデジタルライブラリにアクセスできない人のために、2つのプログラマグループを作成し、同じコードを学習用に提供しました。グループAは通常のコメント付きのコードのみを受け取り、グループBは目次、相互参照、および1990年に可能なすべての機能を備えたきれいに印刷されたリストを受け取りました。

次に、2つのグループにコードに対して特定のタスク（機能の拡張、バグの発見など）を実行するように依頼し、回答の速度と品質の点でスコアを付けました。

グループのバランスをとるために、彼らには同数のエキスパートとジュニアのプログラマーがいました。

さて、グループB（リストがきれいに印刷されているグループ）は、多数のテストでグループAよりも一貫して良いスコアを獲得しました。また、特定のケースでは、グループAの最も専門的な人だけがグループBのジュニアプログラマを上回りました。

記事にはもっとありますが、これは私が記憶から思い出すことができるものです（まだどこかに印刷された記事があるはずです）。

少なくとも私にとって、読み取り可能なコードは、不十分な記述のコードを補うだけのドキュメントよりも価値があることは明らかです。私は、コードを書き直してコメントを削除し、より自己説明的にすることができるかどうかを確認するための挑戦として、コード内のコメントを検討する傾向があります。

よくある常識を除き、確固たる証拠でそれを裏付けることはできません。

引用する研究はありませんが、簡単なルールがあります：2週間後にコードに戻って、自分が何をしたかすぐに分からない場合は、コメントを追加するか、単純化する必要があります。

確かに、コードがどのように機能するかは、コード自体で文書化する必要があります。ただし、コードを保守する唯一の人であっても、長い目で見ればコードが書かれている理由を慎重かつ簡潔に説明するコメントを書くのに費やした時間はほぼ確実です。

ソフトウェアの寿命は主にメンテナンス段階で費やされるため、プログラマーが何が起きているのかを理解するのに役立つプログラマーは、開発者がより早くスピードアップするのに役立つため、ほぼ確実に経済的利益をもたらします。

APIのコード内でわずかに重要ではない文書を作成しても、ほとんど役に立ちません。これは、APIのパワーは、個々のメソッド/オブジェクトがどのように機能するかではなく、ユニット全体としてどのように連携するかに由来するためです。

したがって、実際のドキュメントよりも役立つのは、APIの予想される使用パターンと、明らかな状況（APIの大部分（100％ではない）を使用する）を解決する方法の例を説明する料理本のようなドキュメントです。

与えられた方法が、おそらくまだ発明されていないツールがなければ、ドキュメントを書くことを要求するには主観的すぎるかどうかの決定。

「すべてのパブリックメソッド」や特定のパッケージ内のすべてのクラスなど、ベスト推測のプラクティスは役立つかもしれませんが、特定のユースケースを超えて推奨するにはあまりにもラフです。

私の提案：開発者の良い習慣、文書化するのに重要なメソッド（公式または非公式のAPI、一般的に使用されるスタブメソッド、複雑または難解な）を特定し、それらを自分で管理する方法を教えてください。

（密接に関連する：コーディング標準にあまりにも均一性がありますか？）

^{引用する研究がないことをおologiesび申し上げますが、これは、それを測定しようとする試みが結果に大きく影響し、一般的な結論を導き出すことができない問題であると疑っています。}

この点で、パブリックAPIから「通常の」コードを分離する必要があると思います。通常のコードでは、コードが自己文書化され、散文のように読まれるべきであるという点で、他のほとんどの回答者に強く同意するようになりました。私のコードがそのようなものでない場合、それは通常私のせいなので、文書化するのではなく、リファクタリングする必要があります。単一の抽象化レベルで作業し、正確でわかりやすい名前を付けて、一度に1つのことだけを行う小さなメソッドは、これを達成するための素晴らしい方法になります。

コメントの問題は、コメントが腐敗していることです。コメントを追加するとすぐに、それに付随するコードとは無関係に生活を始めます。コードを変更する次の開発者が関連するコメントも忠実に更新する可能性はどれくらいありますか？私の経験では、ほぼゼロです。いくつかの修正を行った後の最終結果は、コメントが人々を助けるのではなく、困惑させたり誤解させたりすることです。

考えられる例外は、パフォーマンスが最適化されたコード、または特定のアルゴリズムの使用です。この場合、コードがどのように見えるのか、アルゴリズムへの参照などを説明するコメントを追加すると便利です。

このトピックに関する重要な作業は、クリーンコードです。

パブリックAPIである OTOH は、Javadocでも十分に文書化する必要があります。非常に多様なスキルと仮定を備えた無数の見知らぬ人によって使用される可能性があるため、可能な限り簡単かつ明確に使用できるように予防策を講じる必要があります。それはまだ適切なAPI設計の大部分の問題ですが、ドキュメントにも重要な役割があります。

問題は、コードを文書化することで時間を節約できるかどうか、それ以降の開発者が何をするかを理解する必要があるかどうかです。コードが何をするかについて誰も質問せずにコードレビューを飛ばすのであれば、おそらく良い状態にあるでしょう。入力について行う仮定を説明するのはそれほど難しくありません。メソッドが整数オブジェクトを受け取り、文字列オブジェクトを返すとしましょう。intはnullにできますか？最小値/最大値はありますか（integer.MinValue / MaxValue以外）？空の文字列またはnullを返すことはできますか？例外をスローしますか？もちろん、誰でも検査でこれらを見つけることができますが、他の開発者が十分にコードを使用している場合、数分節約することは時間の価値があります。また、コードを確認するためのテストを作成する上で、テスト担当者に足掛かりを与えます。

開発者がドキュメントの作成や保守に時間を費やすべきかどうかという議論が常にあるため、これは確かに興味深いトピックですが、実際には、開発者が自分よりもコードを再訪する場合、コードはよく書かれ、非常によくコメントされるべきですコードがどのように書かれているかを熟考するのに時間を費やす必要はありません。さらに、新しいチームメンバーがチームに参加する場合は、コードが明確に文書化されているため、コードの機能と動作も理解できるため、そもそも何をすべきかを考える必要はありません。

したがって、コードは非常によくコメントされている必要があり、外部のドキュメントを必要としない自己文書化されたコードである必要があります。

私のキャリアの中で、さまざまなレベルのドキュメントと品質のコードを見てきました（ドキュメントと品質は通常の問題であることに注意してください）。文書の作成に費やす時間を、品質の改善に使用することを希望します。単純な場合には、GhostDocのような関数を使用して、関数を調べ、ドキュメンテーションコメントを生成できます。GhostDocが関数が何をするかを示す意味のあるコメントを生成できる場合、明確な名前の関数を持つという目標を明らかに達成しています。

多くの場合、GhostDocは関数が実際に何をするのかを説明し始めることさえできません。あなたの時間はその問題に対処し、（おそらく）ghostdocを使用してコードを自動生成することに費やした方がよいでしょう。

詳細については、Bob MartinのClean CodeとPPPを参照してください。