関連するコードの前後にコメントする[終了]

コメントが適用される行に収まらない（または行けない）と仮定した場合、コードの前または後にコメントを書く必要がありますか？

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

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

回答が特定の言語のみに適用される場合は、どちらを指定してください。

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

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

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

私はコメントが参照するコードよりも上にあることを好みます。以前のコードを参照して厄介なコード行がいくつかの厄介なバグを修正したことを説明しようとするよりも、来ているものについてコードを読んでいる人に伝える方が合理的です触らないでください。

通常、コードは上から下に読むと思います。他に何もない場合、筋肉の記憶により、その下のコードの次の行にコメントが関連付けられます。

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

その理由は、誰かがそれを読み始めると、なぜ何かがそのように行われるのかという明らかな疑問になります。回答のためにスクロールする必要があるポイントまで人が知らない場所。上部にある場合は、すぐそこにあります。

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

さまざまな言語を使用した長年のプログラミングで、コメントが参照するコードの後に新しい行にコメントが配置されている言語のコードを見たことはありません。少なくとも米国では、事実上の標準は、コードの前またはコードに続く同じ行でコメントしています。関連するコードの後に​​コメントを書くと、薬物検査、精神医学的評価、および/またはペンチとブロートーチの日付が必要になります。

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

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskinは、読む価値のあるコメントについてよく考えられたエッセイを書いた。彼はコメントをコードの前に置くか後ろに置くかは言いませんが、彼はコメントをインラインに置くことは決してないと言っています。

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

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

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

対

int i = 0; // make the compiler happy

しかし決して：

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

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

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

これは本当に、あなたの質問に対する答えではなく、あなたの質問のふりと妥当性の否定です。私はまだそれが関連性があり、あなたを助けるかもしれないと思います。そうでない場合、-1が私を支配します。

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

OK、「後」のケースを作成します。コードは常に主要なドキュメントである必要がありますが、コメント（意味的な意味はありません）は括弧付きの説明のようなものです。そのため、説明が必要なコードの下にコメントを置くと、コードは主要な説明として残り、説明のためにコメントを使用します。例えば、

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

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

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

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

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

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

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

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

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

コメントはコードに属していること、そしてコードが何をするかを教えてくれることを知っています。一方、次が表示された場合：

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

繰り返しますが、コメントはそのコードに属していることをよく知っています。これは、コードがどのように機能するかについての明確化です。

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

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

コードは「自己文書化」することができます（そうすべきです）が、メソッドの動作を理解するためにコードのすべての行を読んで理解する必要がある場合。 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スレッドにも同意します- コメントをコードブロックの前ではなく後に追加する必要がありますか？..

私も前もって知りたいです...

私はよくコメント（他の人が書いたものと同様に）をトレースレベルのログステートメントに変換します。これは、通常、それが作るくらい簡単にそれを配置する場所を理解すること。

    // 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");

追加の利点は、困難になったときにログトレースを有効にして、より詳細な実行ログを取得できることです。