web-dev-qa-db-ja.com

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

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

私には、たとえ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.

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

documentationcommentscoding-style
9
Maxpm

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

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

1：コードが書かれている言語に精通している他の誰か。教えるためにコメントを書いたり、情報を補足するためにコメントを書いたりしないでください。

17
Larry Coleman

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

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

これらは、コードをデバッグしようとしているときに役立つリファレンスツールになる可能性があります。多くのIDEは、関数名にカーソルを合わせると、ツールチップでAPIドキュメントも使用します。

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

6
Berin Loritsch

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

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

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

3
Martijn Verburg

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

  1. それらは、数か月/数年後にコードに戻ったときに、コードが何をするかをすばやく思い出させるのに役立ちます。このようにして、メモリをリフレッシュするためにコードを再読み取りして分析する必要はありません。
  2. 彼らはあなたのコードが何をしているのかをあなたのコードを読んだり使ったりしているかもしれない他の人々に中継します。

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

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

本当に？ありがとう！笑

1
Kenneth

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

Javaから、IDEによって自動生成されます。

/**
 * [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

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

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

1
Nicole

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
{
 ...
}
0
Radu Maris

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

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

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

0
dietbuddha