web-dev-qa-db-ja.com

関連するコードの前または後にコメント

コメントが適用される行に収まらない（または行かない）場合、コードの前または後にコメントを記述しますか？

まあ、どこの将来の読者もコメントの範囲を最もよく理解するでしょう。言い換えれば、ほとんどのプログラマー/スクリプト作成者がそのようなコメントを置くところです。

だからほとんどのプログラマー/スクリプト作成者はコメントをどこに置くか：コードの前か後か？

回答が特定の言語にのみ当てはまる場合は、その言語を示してください。

そして、あなたの答えをサポートする受け入れられた仕様またはガイドを引用することができれば、はるかに良いでしょう。

comments
35
msh210

インラインまたはコードの前にコメントを適用する必要があります。コメントの意味は、コード自体を読む必要なしに、コードが何をするかの基本的な理解を得ることです。したがって、説明するコードの前にコメントを置く方がはるかに理にかなっています。

マイクロソフトは、小さなコメントで手順を開始するのは良いプログラミング慣行だと言っています。 （手順の後のコメントについては言及していません） [〜＃〜] msdn [〜＃〜] リンクはVisualBasicに関するものですが、私が思うほとんどのプログラミング言語に適用されます。

23
dasheddot

私はコメントが参照するコードの上にあることを好みます。コードのいくつかの厄介な行がトリッキーだったいくつかのバグを修正したことを説明するために前のコードを参照しようとするよりも、コードを読んでいる人に今後の予定について伝える方が理にかなっています触れないでください。

45
Ryathal

コードは通常、上から下に読み取られると思います。他に何もない場合、筋肉のメモリが原因で、コメントをその下のコードの次の行に関連付けます。

9
Joshua Smith

通常、コメントは、作品と同じインデントに続く行の先頭にある必要があります。たとえば、関数本体の上にコメントがあり、重要なアルゴリズムの開始のすぐ上に1つのライナーコメントがあります。

その理由は、誰かがそれを読み始めると、なぜそのような方法で何かが行われるのかが明らかになるということです。ここで、人は答えを探すためにスクロールする必要があるポイントまで知りません。それが上にあれば、それは見るためにすぐそこにあります。

7
Dipan Mehta

それでは、ほとんどのプログラマー/スクリプト作成者はどこにコメントを付けますか？そのコードの前または後に？

さまざまな言語を使用した長年のプログラミングで、コメントが新しい行の後ろに配置されている任意の言語でコードが表示されたことを覚えていません。米国では、少なくとも、事実上の標準はコードの前またはコードの後の同じ行でコメントしています。関連するコードの後に​​コメントを書き込むと、薬物検査、精神医学的評価、および/またはペンチとブロートーチを使用した日付が求められます。

私が考えることができる唯一の例外は、次のように、以前にコメントされたセクションの終わりを示すコメントです：

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskinが よく検討されたコメントに関するエッセイ を書いたので、一読に値する。彼はコメントをコードの前または後のどちらに置くかについては述べていませんが、インラインでコメントを書き込むことは絶対にないと述べています。

6
Caleb

本当に必要な場合にのみコメントしてください。コードは、可能な場合は常に自己文書化する必要があります。

つまり、配置は依存する可能性があります。コメントに別の行を使用する場合は、コメントにbefore実際のコードを入力します。同じ行にある場合は、後ろに置きます。

// this workaround is required to make the compiler happy
int i = 0;

Vs.

int i = 0; // make the compiler happy

しかし決して：

int i = 0;
// this workaround is required to make the compiler happy
4
Lucero

私は実際にはコメントの大ファンではありません。ソフトウェアエンジニアリングコースで、自己文書化コードのアイデアを紹介されました。コードは、それ自体の100％保証された正しいドキュメントのみです。コメントは更新し、注意深く作成して関連性を持たせる必要があります。厳密なスタイルガイドと意味のある命名規則を使用してC++ショップで作業を始めるまでは、この概念を本当に内部化していませんでした。

時にはコメントが必要です。多くの場合、注意深い変数の命名、空白とグループの意味のある使用、およびコード自体の意味のある論理的な編成により、コメントの必要がなくなります。

これは、あなたが持っていた質問に対する答えとは対照的に、あなたの質問の見せかけと妥当性の否定です。私はそれが関連性があり、あなたを助けるかもしれないとまだ思っています、そして私はジャークではありませんでした。そうでない場合は、-1が私を支配します。

3
Brian Stinar

コードの前にコメントを表示すると、読者がこれから遭遇するコードのコンテキストを理解するのに役立ちます。それらにコードを投げて、彼らがすでに混乱している後に説明するよりもはるかに人道的です。

2
Dan Ray

わかりました。「後」の場合を作成します。コードは常に主要なドキュメントである必要がありますが、コメント（意味論的な意味はありません）は括弧で囲まれた説明のようなものです。したがって、説明が必要なコードの下にコメントを置くと、コードが主な説明として残り、説明のためにコメントが使用されます。例えば、

if(date == CHRISTMAS){
     //Deliver presents
     val (Nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

テストの前にコメントを置くと、読者はcommentを主なものとして読む傾向があり、コードをよく読んでいない可能性があります。

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }
2
Larry OBrien

上記のコメントが最適です。

コメントを含める必要があり、コードが自明ではない場合は、コードのブロックで混乱しないようにしてください。「ああ、それが想定されていることです」を参照してください。

コードは「自己文書化」することができます（すべきです）が、メソッドがどのように機能するかを理解するためにコードのすべての行を読んで理解する必要がある場合。 If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

このトピックについて調べたところ、ほとんどのコンピューターで読み取り可能なドキュメントシステム（Doc XML、Doxygen、Java docなど）は、関連するコードの前にコメントがあることを期待していることがわかりました。その標準との互換性を維持します。

また、SO thread- 前ではなくコードブロックの後にコメントを追加する必要がありますか？ に同意します。

私も前もって知っていると思います...

2
Niranjan Singh

テクニカルライティング（少なくとも英語）からいくつかのアイデアを借用するために、通常、メモや警告のようなものは、そのメモまたは警告が適用される指示またはセクションの前に配置されます。

コードがテクニカルライティングの一種と見なされない理由はわかりません。各ブロックは1つの命令です。英語と同様に、ほとんどのプログラミング言語は左から右、上から下に読み取られます。コメントはコードに関するメモです。コメントは、修正するエラーや、将来の開発者が認識しておく必要があるかもしれないものを識別する場合があります。

この関係に従って、参照するコードのブロックの上にコメントを置く方が適切と思われます。

1
Thomas Owens

コメントは、コメントの種類に応じて、コードの上または下に配置する必要がある場合があります。コードが何をするのかを非常に簡潔に説明する場合は、コードの前に配置する必要があります。コードがどのように機能するかについての技術的な詳細を詳しく説明している場合は、コードに従う必要があります。

幸い、コメントはコードの上または下に移動できますが、空白行を適切に使用することにより、コメントがどのコードに関連するかについて疑問を残すことはできません。もちろん、空白行の使用に注意を払わないプログラマーは、私が何について話しているのかわかりません。あなたがそれらの1人であるならば、この答えをスキップして、あなたの人生とともに進んでください。しかし、空白行に注意を払うプログラマーは、空白行を使用してコードを論理エンティティに分割することをよく知っています。したがって、次のように表示された場合：

[blank line]
/* comment */
{ code }
[blank line]

コメントはコードに属し、コードが何をするのかがわかります。一方、次の場合：

[blank line]
{ code }
/* comment */
[blank line]

ここでも、コメントがそのコードに属していることがよくわかります。これは、コードがどのように機能するかについての説明です。

1
Mike Nakis

私はよくコメント（私のものや他の人が書いたもの）をトレースレベルのログステートメントに変換します。これにより、通常、配置場所がmuchでわかりやすくなります。

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

もう1つの利点は、困難になったらログトレースをオンにして、より詳細な実行ログを取得できることです。

1
gnat