コードのドキュメンテーションを行う方法と、ソフトウェアが（しばしば）不十分にドキュメンテーションされているのはなぜですか？

Question

Java api）のように、十分に文書化されたコードの良い例がいくつかありますが、gitや企業の内部プロジェクトなどのパブリックプロジェクトの多くのコードは十分に文書化されておらず、あまり新人フレンドリー。

私のすべてのソフトウェア開発スティントでは、十分に文書化されていないコードを処理する必要がありました。次のことに気づきました-

コード内のコメントはほとんどまたはまったくありません。
メソッドと変数の名前は自己記述的ではありません。
コードがシステムまたはビジネスプロセスにどのように適合するかについてのドキュメントはほとんどまたはまったくありません。
悪い開発者を雇うか、良い開発者をメンタリングしない。彼らはシンプルでクリーンなコードを書くことはできません。したがって、開発者を含め、誰もがコードを文書化することは困難または不可能です。

結果として、私は多くのコードを調べ、多くの人と話をして物事を学ぶ必要がありました。これはみんなの時間を無駄にしていると思います。また、プロジェクトへの新規参入者のためのKT /ナレッジ転送セッションの必要性も生み出します。

次の理由により、ドキュメントにふさわしい注意が払われていないことがわかりました。

怠惰。
開発者は、コード以外は何もしたくありません。
雇用保障。（誰もあなたのコードを簡単に理解できない場合、あなたは簡単に置き換えることができないかもしれません。）
困難な締め切りは、文書化する時間をほとんど残しません。

したがって、企業やプロジェクトで適切な文書化の実践を奨励および実施する方法があるかどうか疑問に思っています。その複雑さに関係なく、プロジェクトのシステムとコードの適切なドキュメントを作成するために使用する戦略は何ですか？最小限のドキュメントが必要な場合やドキュメントが不要な場合の良い例はありますか？

私見、プロジェクトが完了した後、ドキュメントのレビューが必要だと思います。それが単純で簡潔、例証的、そしてユーザーフレンドリーではない場合、開発者または技術文書エンジニアはそれに対する責任を負い、それを修正するように作られます。私は、人々が一連のドキュメントを作成することも期待していませんし、最初の本のようにユーザーフレンドリーになることも望んでいませんが、何時間もの分析や無駄なKTセッションの必要性をなくすことを期待しています。

この狂気を終わらせる、または緩和する方法はありますか？「ドキュメント駆動型開発」でしょうか。

Arseni Mourzenko · Accepted Answer

コードを文書化する方法は？

すでにヒントがあります。Java APIの文書化方法を見てください。

より一般的には、すべてのプロジェクトに適用される独自のルールセットはありません。ビジネスクリティカルな大規模プロジェクトで作業する場合、ドキュメントは小さなオープンソースライブラリ用に作成するものとは関係がなく、中規模の個人プロジェクトのドキュメントとは関係ありません。。

なぜ多くのオープンソースプロジェクトがうまく文書化されていないのですか？

なぜなら、ほとんどのオープンソースプロジェクトは、楽しいからそうしたプロジェクトに貢献する人々によって作られているからです。ほとんどのプログラマーや開発者は、ドキュメントを書くことは無料で行うには面白くないと考えています。

多くのクローズドソースプロジェクトがうまく文書化されていないのはなぜですか？

（1）良いドキュメントを書き、（2）それを維持するのに莫大な費用がかかるからです。

直接のコスト（ドキュメントの作成にかかるコスト）は関係者に明確に表示されます。チームがプロジェクトのドキュメント化のために次の2か月を費やすことを要求した場合、さらに2か月分の給与が支払われます。
長期的なコスト（ドキュメントの保守にかかるコスト）は、管理者にとっても非常に簡単になり、コストを削減したり遅延を短縮したりする必要がある場合の最初のターゲットになることがよくあります。これにより、ドキュメントが古くなり、すぐに役に立たなくなり、更新に非常にコストがかかります。
一方、長期的な節約（数年前に文書化されているはずの基本的な事柄を理解するためだけにレガシーコードを探索して数日を無駄にする必要がないことによる節約）は、測定が困難であり、一部のマネージャーの気持ちを裏付けていますドキュメントの作成と維持は時間の無駄です。

私がよく観察するのは、

当初、チームは多くのことを文書化する用意があります。
時間の経過とともに、締め切りのプレッシャーと関心の欠如により、ドキュメントの保守がますます困難になっています。
数か月後、プロジェクトに参加した新しい人は、実際のシステムにまったく対応していないため、実際にはドキュメントを使用できません。
これに気づいたのは、管理者が開発者がドキュメントを保守していないことを非難することです。開発者はそれを更新するために数週間を費やすことを求めます。
- 経営陣がそのために数週間を許可した場合、サイクルが繰り返されます。
- 以前の経験に基づいて経営者が拒否した場合、製品にはドキュメントが不足しているため、悪い経験が増えるだけですが、数か月かけて製品の作成と保守に費やされました。

ドキュメントは、テストと同様に、継続的なプロセスである必要があります。 1週間かけて数千のLOCをコーディングするだけで、テストやドキュメントに戻るのはとても大変です。

チームにドキュメントを書くように奨励する方法は？

クリーンなコードの記述、定期的なリファクタリング、デザインパターンの使用、十分な単体テストの追加を人々に促す方法と同様です。

模範を示す。良いドキュメントを書けば、ペアもそれを始めるかもしれません。
ドキュメントの検査を目的とした正式なコードレビューを含む体系的なコードレビューを実施します。
チームの一部のメンバーが優れたドキュメント（またはドキュメント）に特に反感を抱いている場合は、そのテーマについて個人的に話し合い、適切なドキュメントを作成できない原因を理解してください。彼らが時間の不足を非難している場合は、問題の原因がわかります。
数週間または数か月間、ドキュメントの存在または欠如を測定可能にしますが、それに焦点を合わせないでください。たとえば、LOCあたりのコメントの行数を測定する場合がありますが、それを永続的な測定値にしないでください。そうしないと、開発者は、低いスコアを取り除くためだけに長く意味のないコメントを書き始めます。
ゲーミフィケーションを使用します。これは前のポイントと一緒になります。
ポジティブ/ネガティブ reinforcement を使用します。
（ SJuan76によるコメント）を参照）コメントがないことをエラーとして扱います。たとえば、Visual Studioでは、XMLドキュメントを生成するオプションをチェックできます。すべての警告がエラーとして扱われることも確認した場合、クラスまたはメソッドの上部にコメントがないと、コンパイルが停止します。

前の3つの点については、これは注意して使用する必要があります。私はしばらくの間、初心者プログラマーの特にタフなチームでそれを使用しました、そしてそれはそのようなStyleCop準拠のコメントで終わりました：

 /// <summary> /// Gets or sets the PrimaryHandling. /// </summary> public Workflow PrimaryHandling { get; set; }

ええと、特に役に立ちませんでした。

覚えておいてください：プログラマーがあなたと一緒にねじ込みたいときに、自動化されたものは悪いコメントを特定するのに役立ちません。コードレビューとその他humanタスクが役立ちます。

最小限のドキュメントが必要な場合、またはドキュメントが不要な場合の良い例はありますか？

アーキテクチャと設計を説明するドキュメントは必要ありません：

プロトタイプの場合、
タスクを達成するために数時間で書かれた個人的なプロジェクトのために、このプロジェクトがもはや維持されないことをかなり確信している間、
特にクリーンなコードと相まって、その小さなサイズを考えると、コードを探求する将来のすべてのメンテナよりもドキュメントの作成により多くの時間を費やすことは明らかです。

コード内ドキュメント（コードコメント）は、コードが自己文書化されている場合、一部の開発者によれば不要です。彼らにとって、コメントの存在は、まれなケースを除いて、良い兆候ではなく、コードが十分にリファクタリングされていないため、コメントの必要なしに明確になることを示しています。

プロジェクトが完了した後、ドキュメントのレビューが必要だと思います。

プロジェクトが少なくとも1週間に1回配信される場合は、それで問題ありません。プロジェクトがアジャイルでなく、6か月ごとに配信される場合は、定期的なレビューを繰り返します。

Leopold Asperger · Answer

コメントとドキュメントを区別すべきだと思います。コメントは説明的なものですが、一貫性に欠け、コード全体に散らばっています。コメントは自己記述的ではないコードを補うものであってはなりません。代わりに、他のプログラマーにトリッキーな部分を示唆しています。

コードを文書化するかどうかは、プロジェクトの規模によって異なります。確かにeverythingを文書化する必要があると信じている人がいますが、だれが知識を文書化することに反対する勇気があるので、その考えを正当化するのは簡単に思えますか？幸い、ソフトウェア開発は科学ではなく、小さなプログラムの背後にある詳細が不明瞭になっても、世界は崩壊しません。さて、多くの開発者が使用するプロフェッショナルソフトウェアについては、はい、明らかに、コードを文書化する必要があります。しかし、そのレベルでコーディングする立場にあれば、明らかにそれを知っているでしょう。

tl; dr

すべてのプロジェクトを詳細に文書化することを要求している場合は、要求しすぎています。