コードの文書化の方法とソフトウェアの文書化が不十分な場合が多いのはなぜですか？

java apiなど、よく文書化されたコードの良い例があります。しかし、gitや企業の内部プロジェクトなどの公開プロジェクトのコードの多くは、文書化が不十分であり、初心者にはあまり適していません。

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

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

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

次の理由により、ドキュメントには値する注意が払われていないことを学びました。

1. 怠惰。
2. 開発者はコード以外は何もしません。
3. 雇用保障。（コードを簡単に理解できる人がいない場合、簡単に交換できない可能性があります。）
4. 期限が厳しいため、文書化する時間がほとんどありません。

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

私見、私は私達がプロジェクトが渡された後文書の検討があるべきであると感じます。単純で簡潔、説明的で使いやすいものでない場合、開発者または技術文書エンジニアがその責任を負い、修正する必要があります。私は、人々が最初の本のようにユーザーフレンドリーになることを望んではなく、ドキュメントの連を作ることを期待していませんが、何時間もの分析と無駄なKTセッションの必要性を排除すると期待しています。

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

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

すでにヒントがあります。JavaAPIの文書化方法をご覧ください。

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

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

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

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

（1）優れたドキュメントを作成し、（2）維持するのに膨大な費用がかかるためです。

1. 即時のコスト（ドキュメントの作成コスト）は、利害関係者にはっきりと見えます。プロジェクトをドキュメント化するためにチームが次の2か月を費やすように要求した場合、さらに2か月分の給与を支払います。

2. 長期的なコスト（ドキュメントの維持にかかるコスト）は、マネージャーにとっても非常に簡単に目立つようになり、多くの場合、コストを削減したり遅延を短縮したりする必要がある最初のターゲットになります。これにより、古くなったドキュメントの追加の問題が発生し、すぐに役に立たなくなり、更新に非常に費用がかかります。

3. 一方、長期的な節約（数年前に文書化されていたはずの基本的なことを理解するためだけに従来のコードを調査する必要がないための節約）は、測定が困難であり、一部のマネージャーの気持ちを確認しますドキュメントの作成と維持は時間の無駄です。

私がよく観察するのはそれです：

1. 初めに、チームは多くのことを文書化する用意があります。

2. 時間が経つにつれて、締め切りのプレッシャーと関心の欠如により、文書を維持することがますます難しくなります。

3. 数か月後、プロジェクトに参加した新しい人は、実際のシステムにまったく対応していないため、ドキュメントを実際に使用できなくなります。

4. それに気づいたのは、管理者がドキュメントを維持していないことを開発者のせいにしていることです。開発者はそれを更新するために数週間を費やすことを求めます。

   • 経営陣がそのために数週間を許可した場合、サイクルが繰り返されます。

   • 過去の経験に基づいて経営陣が拒否した場合、製品にはドキュメントが欠けているため、悪い経験が増えるだけですが、それを書いて維持するのに数ヶ月を費やしました。

文書化は、テストと同様に継続的なプロセスである必要があります。数千のLOCをコーディングするだけで1週間費やし、テストとドキュメントに戻るのは非常に苦痛です。

チームにドキュメントの作成を促す方法は？

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

• 例でリード。適切なドキュメントを作成すれば、ペアでもそれを開始できます。

• ドキュメントの検査を目的とした正式なコードレビューを含む体系的なコードレビューを行います。

• チームの一部のメンバーが優れたドキュメント（またはドキュメント）に対して特に反感を抱いている場合は、より良いドキュメントの作成を妨げる障害とは何かを理解するために、テーマについてプライベートに話し合います。時間の不足を責めれば、問題の原因がわかります。

• 数週間または数か月間、ドキュメントの有無を測定可能にしますが、それに集中しないでください。たとえば、LOCごとにコメントの行数を測定できますが、それを永続的な測定値にしないでください。そうしないと、開発者は低いスコアを取り除くためだけに長いが意味のないコメントを書き始めます。

• ゲーミフィケーションを使用します。これは前のポイントと一緒になります。

• 正/負の強化を使用します。

• （SJuan76によるコメントを参照）コメントの欠如をエラーとして扱います。たとえば、Visual Studioでは、XMLドキュメントを生成するオプションをチェックできます。すべての警告がエラーとして扱われることも確認すると、クラスまたはメソッドの先頭にコメントがないため、コンパイルが停止します。

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

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

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

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

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

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

• プロトタイプの場合、

• タスクを達成するために数時間で書かれた個人的なプロジェクトの場合、このプロジェクトがこれ以上維持されないことはかなり確実ですが、

• 明らかなプロジェクトの場合、そのサイズが小さく、特にクリーンなコードを考えると、将来のすべてのメンテナーがコードを調査するよりも多くの時間をドキュメントの作成に費やすことになります。

一部の開発者によると、コードが自己文書化されている場合、コード内文書（コードコメント）は必要ありません。彼らにとって、コメントの存在は、まれな場合を除いて、良い兆候ではなく、コードがコメントを必要とせずに明確になるほどリファクタリングされていないという兆候です。

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

プロジェクトが少なくとも週に1回配信される場合、それが道です。プロジェクトがアジャイルではなく、6か月ごとに配信される場合は、さらに定期的なレビューを行ってください。

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

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

tl; dr

すべてのプロジェクトを適切に文書化することを求めている場合、あまりにも多くを求めています。