コメントの作成とドキュメントのベストプラクティス
今日のコメントはかつてないほど簡単になりました。 Javaでは、コメントをクラスにリンクするための素晴らしいテクニックがいくつかあり、Java IDEはコメントシェルを作成するのに適しています。Clojureなどの言語では、関数の説明を関数コード自体を引数として使用します。
しかし、私たちはまだ、良い開発者によって書かれた陳腐化したコメントや貧弱なコメントが多い時代に生きています。私は、コメントの堅牢性と有用性を向上させることに興味があります。
特にここではJava/Clojure/Pythonに興味がありますが、答えは言語固有である必要はありません。
コメントを検証し、「薄っぺらな」コメント（たとえば、マジックナンバーの付いたコメント、不完全な文など）または誤ったコメント（たとえば、スペルの間違った変数などの検出）を自動的に検出する新しい技術はありますか？.
さらに重要なことは、「コメントポリシー」や戦略が受け入れられているかどうかです。コーディング方法についてはたくさんアドバイスがありますが、「コメントする方法」についてはどうでしょうか。
名前/ドキュメントはあなたに伝える必要がありますwhatあなたはやっています。
実装はあなたに教えるべきですhowあなたはそれをやっています。
コメントはあなたに伝えるべきですなぜあなたはあなたがするようにそれをします。
これは物議を醸すかもしれませんが、私のアドバイスは、可能な限りFEWコメントとして書くことです。代わりに、わかりやすい明確なクラス名、変数名、メソッド名を使用してください。できる限り明確な方法でコードを記述してください。そして、これがコードの最も重要な属性であると考えてください（要件を満たしていることを除いて）。できる限りメソッドを明確にし、さらに説明が必要だと思われる場合にのみ、コメントを書き込んでください。
そして、組織的な慣行があります。誰かが何らかの方法でクラスを変更するときはいつでも、コメントがすべて正しいことを確認する必要があります。
他の言語についてはわかりませんが、pythonを使用すると、自己検証コメントの形式である doctests を記述できます。もちろん、実際の単体テストの代わりに使用されますが、特定の機能を文書化するための迅速かつ簡単な方法です。これは、本来あるべきほど明確ではない場合があります。コメントテストが実行できることで、コメントがまだ残っていることを確認できるという利点もあります。正しい（少なくともテストを含むそれらの部分）。
コードコメントを使用してドキュメントを自動的に生成する方法を見つける最も信頼できる場所の1つは、確かに doxygen です。私にはそのようなツールがもっとあるかもしれませんが。
これは、コメントの記述の標準を定義し、ドキュメントを自動的に生成するために従う必要があります。ただし、これにより構造の詳細はわかりますが、意味的には検証されません。たとえば、関数の目的を説明するために誤解を招くような英語を使用しているかどうかを確認することはできません。
これはコメントを構造化する最良の方法ですが、個人的には、コードをそのように保守しやすくするために必要なドキュメントがもっとあると感じています。しばらく前にP.SEで質問がありました コードはオープンソース開発者ツールのドキュメントになることができますか？それはどのくらいの頻度ですか？ もちろん、これは非オープンソースプロジェクトにも適用されます。
コードをより保守しやすくするために、コードの処理方法の構造を作成するのに役立つ外部ドキュメントが存在し、コード内のコメントを表示するように制限することが実際に重要です
コメント書き込みのポリシーを定義したい場合は、コーディング標準に含まれる包括的なアプローチとして含める必要があると思います。これを見てください： スタイルガイドとドキュメント生成ソフトウェアを開発チームに導入する際の落とし穴は何ですか？
通常、コメントはコードの5％未満です。そして実際には、コードレビュー自体は（開発の他の側面に比べて）あまり注意を引くことはありませんが、コメントもレビューすることは実際には困難です。
コメントを検証し、「薄っぺらな」コメント（たとえば、マジックナンバーや不完全な文などのコメント）または誤ったコメント（たとえば、スペルの間違った変数などの検出）を自動的に検出する新しい技術はありますか？.
よく知られている手法があります。「コードレビュー」と呼ばれ、「ペアプログラミング」という姉妹がいます。ここでは「自動的に」何も期待しないでください。
そしてさらに重要なことは、「コメントポリシー」または戦略が受け入れられているかどうかです。コーディングの仕方についてはたくさんのアドバイスがあります---しかし「コメントの仕方」はどうですか？
"Code complete" には、コーディング方法のすべてだけでなく、「コメント方法」、特に自己文書化コードの記述方法に関する章も含まれています。
Java私が楽しんだ1つのソースはOracleの固有のものです Javadocツールのドキュメントコメントの書き方 ：
このドキュメントでは、JavaJavaソフトウェア、Sun Microsystemsで記述されたプログラム）のドキュメントコメントで使用するスタイルガイド、タグ、および画像の規則について説明します。
そして アイテム44：公開されたすべてのAPI要素のドキュメントコメントを記述 ：
APIを使用できるようにする場合は、文書化する必要があります。従来、APIドキュメントは手動で生成されていたため、コードとの同期を維持するのは面倒でした。 Javaプログラミング環境は、Javadocユーティリティを使用してこのタスクを容易にします。Javadocは、特別にフォーマットされたドキュメントコメント（一般的にdocコメントとして知られている）を使用して、ソースコードからAPIドキュメントを自動的に生成します。