コードにコメントを書く際のアドバイスや経験をお聞かせください。それらを最も簡単で有益な方法でどのように書くのですか？コードの一部をコメントするとき、どのような習慣がありますか？たぶん、いくつかのエキゾチックな勧告？

この質問が、コメントのための最も興味深いアドバイスと推奨事項を収集することを願っています。

OK、始めます。

1. 通常、/* */多くの行をコメントする必要がある場合でも、コメントは使用しません。

   利点：このような構文と1行のコメントを混在させるよりも、コードの見た目が良くなります。ほとんどのIDEには、選択したテキストをコメントする機能があり、通常は1行の構文でコメントします。

   短所：IDEなしでこのようなコードを編集するのは難しいです。

2. 完成したコメントの最後に「ドット」を置きます。

   例えば：

   //Recognize wallpaper style. Here I wanted to add additional details
   int style = int.Parse(styleValue);
   //Apply style to image.
   Apply(style);
   

   利点：完了したコメントにのみ「ドット」を配置します。一時的な情報を書き込むことができる場合があるため、「ドット」がないと、戻り、このコメントにテキストを追加する必要があることがわかります。

3. 列挙内のテキストの位置合わせ、コメントパラメーターなど

   例えば：

   public enum WallpaperStyle
   {
       Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
       SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
       Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
       Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
       Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
   };
   

   利点：見た目が良くなり、必要なものが見やすくなります。

   短所：調整に時間がかかり、編集が難しくなります。

4. コードを分析しても取得できないテキストをコメントで記述します。

   たとえば、愚かなコメント：

   //Apply style.
   Apply(style);
   

   利点：コメントに有用な情報のみを含む、明確で小さいコードがあります。

以下の記述のいくつかは、かなり正当化されているものの、非常に個人的なものであり、このように意図されています。

コメントの種類

簡単なバージョンの場合...コメントを使用します。

• データ構造内のフィールドを説明する末尾のコメント（それらは別として、実際には単一行のコメントは使用しません）
• ブロック上の例外的または目的指向の複数行コメント
• ソースから生成された公開ユーザーおよび/または開発者ドキュメント

詳細と（おそらくわかりにくい）理由については、以下をお読みください。

末尾のコメント

言語に応じて、単一行コメントまたは複数行コメントを使用します。なぜ依存するのですか？これは単なる標準化の問題です。Cコードを書くとき、私はデフォルトで昔ながらのANSI C89コードを好むので、常に持っていることを好みます/* comments */。

したがって、私はほとんどの場合これをCで、そして時々（コードベースのスタイルに依存します）Cのような構文を持つ言語のために：

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacsはすてきで、それを私に提供しM-;ます。

言語が単一行コメントをサポートし、Cベースではない場合、単一行コメントを使用するようになります。そうでなければ、私は今習慣を取っていることを恐れています。簡潔にする必要があるため、必ずしも悪いわけではありません。

複数行コメント

これは視覚的に魅力的であるため、単一行のコメントを使用するあなたの教訓に同意しません。私はこれを使用します：

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

それともこれは（私は、多くの場合、それ以上、個人的なコードベースの上またはほとんど著作権表示を除くことはありません-これは私のために歴史的で、私の教育背景から来ているオートフォーマットを使用した場合残念ながら、ほとんどのIDEがそれを台無しに。） ：

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

本当に必要な場合は、後続の位置で使用することが理にかなっている場合は、後続のコメントで前述した内容を使用してインラインでコメントします。たとえば、非常に特殊なリターンケースの場合、またはswitchのcaseステートメントをドキュメント化する（まれに、switchをあまり使用しない）場合、またはif ... else制御フローでブランチをドキュメント化する場合。それがこれらのいずれでもない場合、通常、関数/メソッド/ブロックのステップの概要を説明する範囲外のコメントブロックは、私にとってより意味があります。

ドキュメンテーションコメントをサポートしない言語でコーディングする場合を除いて、これらを非常に例外的に使用します（以下を参照）。その場合、それらはより一般的になります。しかし、一般的な場合、それは本当に他の開発者向けであり、本当に目立つ必要がある内部コメントであるものを文書化するためだけのものです。たとえば、「強制」catchブロックのような必須の空のブロックを文書化するには：

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

これはすでに私にとっていですが、状況によっては容認します。

ドキュメントのコメント

Javadoc＆al。

私は通常、それらをメソッドとクラスで使用して、特にパブリックAPIの場合は機能を導入する（または変更する）バージョンを文書化し、いくつかの例を提供します（明確な入力と出力のケース、および特殊なケース）。これらを文書化する方がユニットケースのほうがよい場合もありますが、ユニットテストは必ずしも人間が読めるものではありません（DSLの使用に関係なく）。

すべてのドキュメント生成フレームワークが後続のドキュメントコメントをサポートしているわけではないので、このために後続のコメントを好むため、フィールド/プロパティをドキュメント化するために少しバグがあります。たとえば、Doxygenにはありますが、JavaDocにはありません。つまり、すべてのフィールドに一番上のコメントが必要です。とはいえ、ほとんどの場合、Javaの行は比較的長いので、私はそれを乗り切ることができます。そのため、末尾のコメントは、許容範囲を超えて行を拡張することで同じように忍び寄ります。Javadocがそれを改善することを検討するなら、私はもっと幸せになるでしょう。

コメントアウトされたコード

Cライクな言語で1つの理由だけで単一行を使用します（厳密なC用にコンパイルする場合を除き、実際には使用しません）：コーディング中にコメントアウトする。ほとんどのIDEには、単一行のコメント（インデントまたは列0に揃えられている）のトグルがありますが、これはそのユースケースに適しています。複数行のコメントにトグルを使用する（または一部のIDEでは行の途中で選択する）と、コメント/コメント解除を簡単に切り替えることが難しくなります。

ただし、SCMのコメントアウトされたコードに反対しているため、コミットする前にコメントアウトされたチャンクを削除するため、通常は短命です。（この質問に対する私の答えは、「編集済みのインラインコメントとSCM」にあります）

コメントスタイル

私は通常書く傾向があります：

• ドキュメンテーションコメントの正しい文法（句読点を含む）を含む完全な文。これらは、後でAPIドキュメントで、または生成されたマニュアルの一部としても読まれるようになっています。
• 適切にフォーマットされているが、複数行のコメントブロックの句読点/大文字の制限が緩い
• 句読点なしの後続ブロック（スペースのため、通常はコメントが短いものであるため、括弧で囲まれたステートメントのように読みます）

Literate Programmingに関する注意

Donald Knuthがこの論文で紹介したように、Literate Programmingに興味を持ちたいかもしれません。

読み書きのできるプログラミングパラダイム[...]は、コンピューターが課す方法と順序でプログラムを書くことから遠ざかり、代わりに、プログラマーが論理と思考の流れによって要求される順序でプログラムを開発できるようにします。2 Literateプログラムは、エッセイのテキストのように、普通の人間の言語での論理の中断のない説明として書かれています[...]。

読み書き可能なプログラミングツールを使用して、読み書き可能なソースファイルから2つの表現を取得します。1つはコンピューターによるさらなるコンパイルまたは実行に適した「絡み合った」コード、もう1つはフォーマットされたドキュメントとして表示するものです。識字ソース。

サイドノートと例：underscore.js JavaScriptフレームワークは、私のコメントスタイルに準拠していないにもかかわらず、適切なドキュメントコードベースと整形式の注釈付きソースの非常に良い例です。ただし、 APIリファレンス）。

これらは個人的な慣習です。はい、私は奇妙かもしれません（そしてあなたもそうかもしれません）。それのOK、限り、あなたのように従うと、あなたのチームのコード規則に準拠し、ピアで作業する場合、または根本自分の好みを攻撃しないとcohabitateきれい。それはあなたのスタイルの一部であり、あなたをコーダー（またはあなたがつながりを持っている考え方や組織の信奉者）として定義するコーディングスタイルを開発することと、一貫性のためのグループの慣習を尊重することとの間に細かい線を見つける必要があります。

大学に行ったとき、私はいつもすべてのコード行とすべてのメソッドヘッダーをコメントするように教えられました。それはあなたが疑いなくそれをしたほどの程度でドラムに入れられた/教え込まれた。さまざまな企業のいくつかのアジャイル開発チームの一員であったため、ブルームーンに一度コメントを書くことができると言えます。

この理由は2つあります。まず、101個の異なる処理を行う長いモノリシックメソッドを記述する必要はもうありません。クラス、メソッド、変数名は自己文書化する必要があります。例として、次のログイン方法を取り上げます。

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

これは、はるかに読みやすく、おそらく再利用可能なものに書き換えることができます。

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

ログインメソッドから何が起こっているかを明確に見ることができます。これは余分な作業として表示される場合がありますが、メソッドは小さく、1つのジョブしかありません。さらに、メソッド名は説明的であるため、メソッドヘッダーコメントを記述する必要はありません。メソッドが多すぎる場合、これは、関連するメソッドをUserAuthenticationServiceなどの別のオブジェクトにリファクタリングする必要があることを示しています。オブジェクトには1つのジョブしかないことを忘れないでください。

第二に、コメントを含め、作成するコードのすべての部分を維持する必要があり、コメントが多いほど維持する必要があります。クラスまたは変数の名前を変更すると、コンパイルエラーが発生しますが、コードのセクションの動作を変更したり削除したり、関連するコメントを更新しなかったりすると、コンパイルエラーは発生せず、コメントが混乱を引き起こします。

APIを作成している場合、公開されているインターフェイス、クラス、列挙にはドキュメント用のヘッダーコメントが適切に記述されている必要があります。

形式ではなくコンテンツに重点を置いてください。たとえば、あなたの例のコメントは新しいことを何も教えてくれません。それらはコードを読むことを損なうので価値がないよりも悪いです、そしてこれらのようなコメントはせいぜい元のプログラマーが彼がそれを書いた時にやっていたと思ったことへのあいまいな参照です。コード例から、「apply（Style）」というスタイルを適用していることがわかります。ソースを読むことができます。私はあなたの心を読むことができません-なぜあなたはそれをしているのですか？コメントが私に伝えるべきことです。例えば

//Apply style.

Apply(style);

あるべき

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

私たちのほとんどは、既存のコードでチームで作業し、他のチームが行う方法、既に行われている方法をフォーマットします。可愛さよりもはるかに重要な一貫性。

可能な限り、コメントが完全に無関係になるようにコードを記述してください。重要な概念が明らかになるような方法でコードを記述できない場合にのみ、コメントを追加してください。

私自身の好みは、それを本当にシンプルに保つことです。私はすべての種類の凝ったフォーマットを避けます。これの主な理由は、ソースコードは最も単純なテキストエディターでも快適に編集できるはずだと思うからです。また、テキストの段落をハードラップすることはありませんが、代わりにエディターにソフトラップを実行させます（改行は追加しません）。

私はしばしばそのようなコメントを見ます、そしていくつかのツールはそれを自動的にそのように生成します：

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

2行少ない：

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

IDEやエディターは、メモ帳レベルの少し上にあり、コメントを検出して、異なる色で印刷できます。行の先頭をアスタリスクで飾る必要はありません。

インデントにタブを使用すると、いくつかのバイトを節約できます。

コメントをグレーのトーンでレンダリングする洗練されたエディターを使用しない場合、大量のアスタリスクが強調として機能し、注意を引き付けます。これは正しいことの反対です。

これが、仕事のコード全体で見つけた「アンチパターン」です。「変更ログ」としてのコメントの使用。それがバージョン管理システムのログの目的です。コードには次のようなものが散らばっています。

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

通常、コメントアウトされた古いコードが含まれていることがよくあります（これもVCSシステムのポイントなので、新しいコードが記述された後にコード内にある必要はありません）。また、回避する必要があるのは、「なぜこれが必要なのか」などのコメントの繰り返しです。またはさらに悪いことに、「これはおそらく名前を変更する必要があります」（名前を変更するための洗練されたツールがあるため、そのコメントを書くのに時間がかかったので、名前を変更することができました）。繰り返しますが、私はこれらのコメントの両方に定期的に対処します：

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

1. doxygenなどのドキュメントシステムを選択して、 それを使い続けます。作成されたドキュメントを確認してください。
2. コードベースを初めて使用し、ドキュメントを読んでいる人を想像してみてください。インターンは実際にそのために役立ち、既存のドキュメントベースと簡単なタスクで新しいものを座って、彼らがつまずいたら、あなたが彼らに再び行くようにあなたに言ったものがドキュメントに行くことを確信します。
3. レビュープロセスでドキュメントコメントをチェックポイントにします。

コードリーダーは通常、次の3つの質問に答えようとしています。

1. このクラスまたは関数は何をしますか？これに答えるのが難しい場合は、やりすぎです。文書化が困難なコードは、通常は間違っています。
2. どうやって使うの？例で十分かもしれません。
3. そのコードは驚くべきものです。どうしてそんなことをしました？最も可能性の高い回答：サードパーティのコンポーネントのバグを回避するには、明らかな手法が遅すぎることが判明したため

それ以外はすべてコードで表現する必要があります。文章を書くように、これは芸術であり、多くの練習が必要です。コードが理解できるかどうかを知る唯一の方法は、他の人にコードを読ませることです。何かを理解していないときは、言葉で説明しないでください。コードを改善します。最後の手段としてコメントを追加します。

「2倍の長さ」が表示された場合、「測定単位は何ですか？」コメントを追加しないでください。変数名を変更します。コードのブロックが表示され、「これは何をしますか？」と言った場合、コメントを追加しないでください。意味のある名前で関数を抽出します。17個の引数が必要なために関数を抽出できない場合は、コードをリファクタリングします。