web-dev-qa-db-ja.com

コードコメントのピリオド/フルストップについてどう思いますか？

私は これはSO Tavern で尋ねられた）を見たので、ここに質問を投稿しています。興味深い質問だと思いました（もちろん、それはですが、ここでは問題ないと思います。）

コードのコメントにピリオドを追加しますか（または、OPが書いたように、「完全停止」）。

関連性を保つために、なぜ？

source-codecommentscoding-stylegrammar
28
Moshe

完全停止は文を終了するためのものですが、コメントがコードで囲まれた1文のみで構成されている場合、私の考えでは完全停止は必要ありません。最初の文字を大文字にしないことさえある。一方、詳細な複数行コメントには完全な句読点が必要です。

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}
29
mojuba

はい、コメントは英語であり、適切な英語では句読点が使用されるためです。

27
Dominique McDonnell

コードのコメントにピリオドを追加しますか（または、OPが書いたように、「完全停止」）？

関連性を保つために、なぜですか？

同じ理由で、「通常の」テキストを書くときにそれらを追加します-それらは書面での言語の一部であり、それらについて何も特別なことはありません。私は、1文（1行）のコメントと段落全体を書くときにも同じように使用します。

ソースコードは通常のテキストではないため、別のルールを使用しています。シンプル;-)

17
Rook

コメントを書く場合は、英語で書かれているとよいでしょう。それはケースケースなので、適切に句読点を付ける必要があります。そうでなければ、怠惰になります。

9
quickly_now

全文（またはそれ以上）を書けば、はい。私がそうしない場合は、時々ノー、しかし通常はいまだです。

私は時々頭がおかしくなり、感嘆符や疑問符などを使用します;）

理由については、それは私がそのようなことに特にこだわっているからであり、適切な句読点が多くの明確さを追加できると思うからです。

5
Adam Lear

他の回答とその人気により、完全な停止は長いコメントで高く評価され、ワンライナーではおそらく回避できることが明らかになりました。

関連するかもしれないもう1つのポイントは、感嘆符を避けることです特に複数。例：

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

そして

    // This code really sucks!

一方、疑問符は時々非常に役立ちます：

    // TODO: What does Crojpler.bway() actually do?
3
Dan Rosenstark

場合によります。コードブロックの機能を説明する大きく適切な段落を書く場合、他の適切な記述と同様に、適切に句読点を付けます。 OTOH、コードを1行だけコメントするときはコメントしません。

どうして？ -SMSメッセージに省略文を使用する可能性があるのに、適切な文章を使用してメールを作成する理由と同様です。あるケースでは、適切なテキストブロックを書くために座っているので、自動的に「適切に実行する」一方で、もう1つはポイントを説明するための簡単なメモです。

私のコードの実際の例：

簡単なコメント：

// check for vk_enter

「適切な」メソッドのドキュメント：

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.
1
Bobby Tables

はい、私はこの方法で適切なコーディング規則を作成し、コードをレビューする第三者がきちんと読みやすいコードを作成すると思います。

1
Aditya

期待するXMLコメントを作成するとき、常に適切に大文字と句読点を付けますIntelliSenseおよびで生成されたドキュメントに表示されます。これらはより正式な構成要素であり、そのように扱う必要があります。

ただし、コードブロックの本文に表示されるコメントは、できるだけ明確にする必要があります。それをどのように達成するかはプログラマ次第です。

0
Matt DiTrolio