コメント/コード内ドキュメントスタイル

これはばかげた質問かもしれませんが、しばらく頭の後ろにいて、他のどこにもまともな答えを見つけることができません。

私には、説明が1つしかない場合でも、各パラメーターと説明を明示的にリストする必要があると言う先生がいます。これは多くの繰り返しにつながります：

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

コード内のドキュメントを書くとき、あなたはどのくらい詳細ですか？

手始めに、あなたの例の "Function："行は完全に冗長であることに同意します。学校でそのタイプのコメントを追加するように教えられた人々が、そのタイプのコメントを製品コードに追加し続けたのも私の経験です。

良いコメントはコードの内容を繰り返さないでください。彼らは「なぜ？」という質問に答えます。「何？」の代わりに または「どうやって？」これらは、入力に関する期待、および特定の条件下でのコードの動作をカバーしています。アルゴリズムYではなくアルゴリズムXが選択された理由を説明します。要するに、コードを読んでも他の誰かに明らかではないこと¹です。

^{1：コードが記述されている言語に精通している他の誰か。教えるコメントを書かないでください。補足情報にコメントしてください。}

いくつかの言語には、Ruby、Java、C＃、C ++（コマンドラインツールを使用）などのAPIドキュメント生成機能があります。そのように考えると、APIドキュメントを書くことがはるかに重要になります。結局のところ、それは「どうすればよいですか...」という質問に答えます。そのFunction: MyFunctionため、関数の名前が誰にとってもわかりやすい場合など、繰り返しを行うことはありません。API doc生成ツールは、私にとってそれを行うのに十分スマートです。ただし、次の詳細は特にパブリックメソッド/関数で役立ちます。

• 要約（それが何をするか、関連する場合はそれを使用する方法の要約）
• パラメータのリストと期待されるもの
• 戻り値（出力）はどうなるか
• 明示的にスローできる例外とその理由

これらは、コードをデバッグしようとするときに便利な参照ツールになる可能性があります。多くのIDEは、関数名にカーソルを合わせると、ツールヒントでAPIドキュメントも使用します。

これらの機能がない言語の場合、コメントは役立ちますが、それほど多くはありません。

それがパブリックAPIメソッドである場合、はい、特にパラメーターと予想される動作に関する詳細なドキュメントを提供する必要があります。多くの人は、これがプライベートメソッド/関数、YMMVについてはリラックスできると感じています。

全体的に、私は、わかりやすい変数名を使用して、クリーンなコード（1つのことと1つのことをうまく行う小さなメソッド/関数）を書くことを好みます。これにより、コードの多くが自己文書化されます。ただし、エッジケース、並行性の使用、複雑なアルゴリズムの使用については常に文書化します。

要するに、今から3か月後の午前3時に着るのは少し悪いと自分を考えてください。パラメータ（ブールフラグ）の意味を理解するのではなく、すばらしい公開ドキュメントを感謝します。

これは、ほとんどの-Docフレームワークがコード内ドキュメント（JavaDoc、PHPDocなど）を解析する方法に似ています。

IDEによって自動生成されたJavaから：

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

これは、組み込み言語機能のドキュメントを生成するために使用される形式と同じです-例：http : //download.oracle.com/javase/6/docs/api/java/lang/String.html

この形式は、コードとのインターフェース方法をサードパーティのユーザーに明確に示すため、非常に役立ちます。関数が内部でのみ使用されるプライベートメソッドである場合、それは少し無意味になる可能性があります-しかし、あなたがすべての区別を経験するまで、先生はあなたを良い実践に導こうとしていると思います。

私が幾分冗長であると私がしばしば思う唯一のビットは、戻りの説明です-通常、それは私のメソッドの説明とほとんど同じです。

コメントには2つの目的があります。

1. 彼らはあなたが数ヶ月/数年後にそれに戻ってきたときにあなたのコードが何をするかを素早く思い出させるのに役立ちます。この方法では、メモリを更新するためにコードを再読み取りして分析する必要はありません。
2. 彼らはあなたのコードを読んでいるか、あなたのコードを使って作業している他の人々に中継します。

もちろん、これに取り組むには多くの異なる方法がありますが、より徹底的で一貫性のある方が優れています。効果的なコメントは、効果的なプログラミングと同じように学ぶのに時間がかかります。あなたが取り組んでいるものは実際にはそれを正当化するのに十分な大きさではないが、彼らはあなたにそれを紹介しようとしているだけなので、学校でのコメントのポイントを見るのは難しいことに注意してください。そして、通常、それを教える方法は、教授のスタイルであり、決して標準的なものではありません。あなたのために働くものを開発します。そして覚えておいてください...ばかげたコメントのようなものがあります！:)例：

a += 1; //adds 1 to the value in a

本当に？ありがとう！笑

私はPHP Webサイトのドキュメントが好きなので、インラインコメントには同様のものを使用し、PHPDoc構文を使用します。以下の例を参照してください。

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

そして、@ Larry Colemanが言ったように、インラインコメントは、なぜコードの一部を実行したのかを示すはずです。

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Doc生成のサービスに含まれている場合、冗長なコメント（苛立たしくはありますが）はおそらく良いことです。コメントを常に最新の状態に保つことはチームの目標にする必要があります。

それが単にコメントのスタイルだとしたら、私はそれに問題を抱えているでしょう。過剰なコメントは、ヘルプと同じくらいコードを傷つける可能性があります。古くなって誤解を招くようなコード内のコメントに遭遇した回数を数えることはできません。私は通常コメントを無視し、コードとコードのテストを読んでそれが何をするか、何が意図されているかを理解することに集中します。

私はむしろ、明確で簡潔なコメントなしのコードが欲しいです。説明的なアサーションまたはメソッドを使用したテストをいくつか提供してください。私は満足しており、情報を提供されています。