ドキュメントを記録するための好ましい方法
教えられたソフトウェアエンジニアなら誰でも知っているように、優れたソフトウェアプロジェクトにとってドキュメントがいかに重要かを知っています。 JavaDocコメントのほかに優れたドキュメントを保証するためのベストプラクティスを教えてください。
私の意見では、ドキュメントにはjavadocコメントを含めるだけでなく、将来および現在のプログラマーに人間が読めるテキストを保証する必要があります。
私の考えは、おそらく紙やウィキを保証することです。 JavaDocなどの標準ソリューション以外にドキュメントの記録に役立つソフトウェアはありますか？.
「ドキュメンテーション」と見なすことができる情報はたくさんあります。これが私の要約であり、それぞれのベストプラクティスがいくつかあります。
クラス、メソッド、関数、および変数名。これは、読み取り可能なコードを持つために重要です。他のすべてのドキュメントは簡単に古くなる可能性がありますが、コンパイラが実際にコンパイルするテキストはほとんど定義上できません。これはソフトウェアの機能への究極の参照であり、ここでは適切な命名を優先する必要があります。
インラインコメント。関数とメソッド内で、機能セクションを分離し、トリッキーなアルゴリズムを説明するための適切なコメントを持つことは価値があります。それらが古くなっていないことを確認してください。
JavaDocスタイルのコメント。これらは、安定したコードベースを簡単に閲覧するためのWebページの生成に最適ですが、アクティブな開発中のコードでは価値が限られている可能性があります。これらは、特にシステム全体で使用されるコードの場合、コードが安定した後に作成および作成するのが最適です。これらは、1か所でのみ使用されるコードにはあまり価値がありません。
開発者向けドキュメント。これには、ソフトウェアの開発を開始するためのガイド（インストールするパッケージ、ビルド手順、デバッグのヒント、コーディングスタイルなど）が含まれます。これは、最初にプロジェクトを開始するとき（または不在後にプロジェクトに戻るとき）に役立ちますが、他の時間にはほとんど使用されません。ピンチでは、この情報は他のチームメンバーから取得できます。
ユーザー/管理者/オペレーターのドキュメント。これには、ソフトウェアのインストール、管理、および使用方法に関する情報が含まれます。お客様は困っているときにこれを高く評価しているので、良いはずです。理想的には、ソフトウェアは自明である必要がありますが、それが不可能または適切でない場合もあります。これは、優れたライティングスキルを持つ人が書く必要があります。
これらすべての種類のドキュメントはソフトウェアの価値に貢献しますが、5つのグループの中で、1と5が最も重要であり、3が最も重要ではないと言えます。残念ながら、3つを除いて、問題のドキュメントの生成を容易にするソフトウェア（テキストエディタ以外）はありません。一般に、ドキュメントと高品質のコードの記述に関する優れた本がたくさんあります。私のお気に入りの1つは コード完了 です。
JavaDocのドキュメントは多かれ少なかれ詳細かもしれません。たとえば、インラインドキュメント（.NETではJavaDocに似ています）は 私が取り組んでいるプロジェクトの1つ でかなり冗長であり、メソッドの説明だけでなく、考えられる例外、メソッドの使用方法を示す例（コメントにデモソースコードを含む）など。
冗長なインラインドキュメントを用意することも良いことですが、それを忘れないでください。
多くのことはソースコード（およびソースコードファイルのドキュメント）では説明できません。どうですか：
- セキュリティ上の懸念？
- プロジェクトを展開する方法についての指示？
- 環境についての詳細？
- スタイルガイドライン？
- 等.
優れたインラインドキュメントは優れたものですが、これは優れた読みやすいコードの記述を避けるための言い訳にはなりません。特に、明示的なドキュメントを避けるために、コードを改善する方法を考えてください。たとえば、.NETにはコードコントラクトがあり、コントラクトが古くなることはありません（またはめったにありません）ことを保証しながら、コードの明確さを向上させます。
どうして？
最良のドキュメントは、明確な目的とプロセスを備えた明確に記述されたコードです。その場合、何が行われているのかを説明するコメントは不要です。説明するコメントなぜコードが存在することは、文脈から明らかではないにしても、役に立ちます。
根本的な質問は次のとおりです。あなたが考えているドキュメントの目的は何ですか？
それ自体のための文書化は、努力の無駄かもしれません。