なぜコードを文書化する必要があるのですか？
可能性のある複製：
「コメントはコードの匂いです」
私は、古いCOBOLのような言語/フラットファイルレコードストレージシステムを使用する保険会社の大学院ソフトウェア開発者です。コードは完全に文書化されておらず、コードのコメントと全体的なシステム設計の両方が含まれており、Webには助けがありません（業界外では使用されていません）。現在の開発者は10〜30年の間システムに取り組んでおり、コードを読むだけで何が起こっているのかを理解でき、コメントを信頼できないため、ドキュメントが不要であることを確信しています。
なぜそのようなシステムを文書化する必要があるのですか？
なぜそのようなシステムを文書化する必要があるのですか？
私の意見では、生産的に使用され、人々によって保守されることになっているすべてのシステムは、そのサポートを担当する人々の手の届くところに文書を用意する必要があります。その理由は、単に次の理由からです。
すべての開発者が同じIQを持っているわけではありません-スマートジョンだけでなく、すべての開発者にそれを入手してもらいたいのです。
すべてのコードが明白であるとは限りません。複雑なアルゴリズムはすべての人が読むことはできません。
ビジネスルールは読みやすいかもしれませんが、なぜそこにあるのかを示すだけではありません。たとえば、レポートアプリケーションの次の行を見てください。
if (lastname>="ZZ") then goto loopwhatは発生していますが、-whyは発生していません。
詳細を見つけるには長い時間がかかり、それはビジネスのお金の無駄です。
システムの各要素間の依存関係は、常に明白であるとは限りません。特に、各ジョブが独立したプログラムのように見えるが、実行シーケンスは、特定のルール（毎月の実行など）に従って処理する必要があるパッケージであるバッチプロセスで特に重要です。
ドキュメントは、ログと結果が正しいかどうかを理解するのに役立ちます。
各コンポーネントの機能を理解すると、ビジネス上の質問に答えることができます。スーザンが経理から電話をかけて、今月5つの小切手を逃しているのはなぜですかと尋ねます。一部のプログラマーは応答するかもしれませんが、私はジョブを実行してエラーを出しませんでした-これはスーザンの助けにはなりません。システムのどの部分が小切手を処理するためのデータ抽出を行うかがわかっていて、印刷する小切手を適格とするために適用されるビジネスルールが何であるかがわかっている場合、有用な回答を提供できます-バグがないと仮定します。
ドキュメントは、コードに挿入されたコメントをはるかに超えていることに注意してください。これらには、ERD、ビジネス要件ドキュメント、設計ドキュメントなどが含まれます。
つまり、優れたドキュメントは、システムを維持するために必要な制御を開発者に提供します。
そのシステムの開発者は自分の仕事を保護しようとしているだけです。
コードが十分に文書化され、理解できる場合、開発者は簡単に置き換えることができます。明らかに、コードが完全にドキュメントに欠けており、難解なCOBOLアートで訓練されたものだけを除いて解読できない場合、それらの開発者を削除して置き換えるのは簡単ではありません。
あなたが言ったように、それらの開発者は10年以上そこにいます。彼らはおそらく10万ドルをはるかに上回っており、おそらく20万ドルに近いでしょう。マネージャーが大学からのジュニア開発者（またはオフショア開発者）と交換して、給与を1/2から1/3にするという誘惑があると私は確信しています。
これはもちろん複雑さに依存しますが、一般的には答えは非常に簡単です...はい！あなたはそれがCOBOLのような言語だと言いますが、何人がこの言語を知っていますか？
この開発者が心臓発作を起こしたり、利用できなくなったりした場合、新しい人がデザインに関する情報を必要とするときに誰が説明できるでしょうか？
時は金なりです。スピードを取り、利益を生む何かを始めるのです。コードをめちゃくちゃにする前に、ドキュメントを参照して物事がどのように機能するかを理解する方が速くなります。
外部の助けを借りる必要がある場合、彼らがドキュメントを読むことができれば、より安く、より速くなります。
コード自体を見ても見えないものは他にもあります。将来の拡張についての考え。いくつかのコードは本当にばかげているように見えるかもしれませんが、次の機能または拡張のために設計されています。
会社のビジネスがこのプログラムに依存している場合は、本当に文書化して、何かが起こった場合（たとえば、主要な設計者が腹を立てて去った場合）に問題をすばやく修正できるようにする必要があります。
ドキュメントを書くのは 'A'に苦労します。 Doxygen などの自動生成ドキュメントをお勧めします。これは、コードを読み取り、呼び出し図を描画し、コメントをヘルプファイルまたはHTMLマニュアルに収集する優れた無料ツールです。 Cobolライクな言語を処理できるかどうかはわかりませんが、それを拡張してより多くの言語を処理できるスクリプトやバリアントがあります。
通常、プロジェクトを開始する前に設計を失う文書を作成し、コードにDoxygenスタイルのコメントを付けて文書化します。それは、新しい人々をすぐにスピードアップするのに十分効果的でした...
一般的にコメント/ドキュメントが不要であることに同意するかどうかはわかりません。ただし、チームと私がコードを書くのが上手になるにつれ、コメントの量を減らすことができるようになったことがわかりました。例えば。メソッドがProcessFile（）と呼ばれる場合、「この関数はファイルを処理する」というコメントを追加する必要があるのはなぜですか？
ただし、コメントが非常に役立つ場合があります。たとえば、特定のステートメントの目的が明確でない場合。非常に単純な（単純化した？）例をとると、ビットの右シフトとして2による除算を実装できます。
コメントの量はおそらく、使用するプログラミング言語にも依存します。たとえば、アセンブラーのコードをJavaまたはC＃などの高水準言語で記述されたコードと比較します。ここでも、スペクトルがあると思います。
ただし、コメントは一般的に信頼できないことに同意します。その理由は、特に一定の期間のあるコードでは、コメントが同じである間にコードが変更された可能性があるためです。コードとコメントが同期していません。最悪の場合、このタイプのコメントは開発者を誤った結論に導く可能性があります。私の推奨は、コメントに含まれる情報の使用に常に注意することです。
要約すると、優れたコードではコメントが少なくてすみ、極端な場合は自明です。私の経験であるテスト駆動開発（TDD）でより良いコードに移行するには、シンプルな設計と無慈悲なリファクタリングが最良のツールです。ただし、これらのツールのいずれも、適切で合理的な選択を行うために適切な考え方を置き換えるものではありません。
この質問にはいくつかの側面があります。
コード内のコメントに問題があります。コードを変更すると、コメントも変更する必要があるという点で、メンテナンスプログラマーにオーバーヘッドが発生します。ここで、関数/メソッドを呼び出すコードに、そのメソッドの動作に関するコメントが含まれている場合があります。そのため、メインテナンスプログラマは、コメントを更新するためのコメントについて知っていますか？おそらく違います。
この場合、他のすべての既存のプログラマーは、古くなったコメントを信頼するよりもコードを読む方が簡単だと感じています。
あなたがコードを理解している難しさは、プログラミング言語がよく知られていないことである可能性はありますか？必要なコメントではなく、このプログラミング言語でのトレーニング、実践、経験が本当の問題ですか？