コードコメントのピリオド/フルストップについてはどう思いますか?[閉まっている]


27

私が見た、これはSO居酒屋に尋ねたので、私はここに質問を投稿しています。面白い質問だと思いました。(もちろん、SOに属していませんが、ここでは問題ないと思います。)

コードコメントにピリオドを追加しますか(またはOPが書いたように「フルストップ」)。

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


2
時々私はそうし、時々私はしません。コメントと読みやすいものに依存します。
ティム

回答:


29

完全停止は文を終了するためのものですが、コメントがコードで囲まれた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; 
}

4
+1。これは私のコメントスタイルに非常によく似ているので、偽のdeja vuが表示されました。:)
ボビーテーブル

26
いいえ、終止符は文の終わりを示すためのものです。1つまたは複数あるかどうかは関係ありません。
ルーク

2
<joke> intの境界を超えているかどうかを確認する方が良いでしょうか</ joke>
ダンローゼンスターク

2
@Yar:平均は常にaとbの間であり、定義により常に境界内にありますよね?;)
mojuba

8
私の文字列はすべてヌルで終了しているので、適切なコメントは常に「\ 0」で終わる必要があります。あなたのコードを見ている次の人が心の終わりを過ぎて読むことは望ましくありませんか?
CodexArcanum

26

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


2
テキストメッセージはどうですか?
モシェ

4
@Moshe、テキストメッセージはほとんど適切な英語ではありません。
ドミニクマクドネル

8
ほとんど適切な英語ではありませんが、句読点を使用しています。句読点は、著者が意図したとおりに読者をガイドするためのものです。これは、どの言語にも当てはまります。
cjmUK

@cjmUK、笑、はいので、私はモシェは私が定期的に壁に私を押し上げた「さようならそこWD B GR8のcuこと」のようなメッセージを受け取ると、我々は、句読点を使用しないことを理由として、それを意味考えI.を行う
ドミニク・マクドネルを

私はすべての方法で
私は夢を見る

17

コードコメントにピリオドを追加しますか(またはOPが書いたように「フルストップ」)。

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

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

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


私の友人は、インターネット上にあるため、電子メールの単語を決して大文字にしません。私にとって、SMSのような技術的な制限に文章を適合させることは問題ありませんが、メールやソースコードは文字や書籍のテキストとどのように異なりますか?
-LennyProgrammers

1
@ Lenny222-ここで何を求めているのかわかりません。電子メールは通常のテキストのように書く必要があります。あなたが言うように手紙を書いているように。それらが実際にどのように書かれているか(そして、SMS、ああ、SMSを始めてはいけない:)ソースコードは、独自の構文規則を持っているため、通常のテキストと同じ規則に従いません。
ルーク

2
私にとって、ソースコードのコメントは人間が読むことを意図しています。一部の情報が別の仕様書にあるのか、ソースコードのコメントに埋め込まれているのかで違いが生じるのはなぜですか?
LennyProgrammers

@ Lenny222-何かが私に起こったので、私たちの間に誤解がないように。私たちは今ソースコードについて話しているのでしょうか、それともそこに埋め込まれているコメントですか?それが2番目のケースである場合、私はあなたを誤解したので、謝罪します。その場合、通常のテキスト(コメント用)と同じルールが適用されます。実際のソースコード(コンパイラ/インタプリタによって読み取られるソースコード)では、同じルールがどのように続くかわかりません。
ルーク

1
はい、知らずにお互いに同意すると思います。;)
LennyProgrammers

9

コメントを書く場合は、英語で書いてください。その場合、適切に句読点を付ける必要があります。そうしないと怠け者になります。


1
ピリオドは文の終わりです。コメントは必ずしも完全な文ではありません。
ジョンB.ランベ

一般的に、コメントは文章でなければなりません。そうでない場合は、なぜそうでないのかを尋ねるべきです。あなたのコメントが短すぎて文章ではない場合、それらはおそらく明らかであり、したがって余分なものでしょうか?
すぐに_17

5

完全な文(またはそれ以上)を書く場合、はい。そうでない場合、時々いいえ、しかし通常はい。

私も時々気が狂って、感嘆符、疑問符などを使用します;)

理由については、その理由の一部は、私がそのような特定の理由だけでなく、適切な句読点が多くの明確さを追加できることを発見したからです。


疑問符を使用している場合、独自のコードを理解していますか?
モシェ

@Moshe:私が自分のコードをまだ完全に理解していない場合、これらは通常TODOにあります。
アダムリア

2
@Moshe-コメントに質問を含めることができないのはなぜですか?質問は修辞的です。実際、私たちはよく私たちですか?私のコメントで-ロジックのドライな説明ではなく、条件付きコードを説明するときは、ロジックを質問として説明する方が明確なことがよくあります。例えば、「適格基準は満たされていますか?いいえの場合、ユーザーに警告を表示します。」
cjmUK

1
大規模なプロジェクトや多くの共同制作者と協力する際に​​、これらの質問のコメントが最も重要であることがよくあります。
LennyProgrammers

3

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

関連する可能性がある別のポイントは、感嘆符、特に倍数を避けることです。例:

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

そして

    // This code really sucks!

一方、疑問符は時々非常に便利です。

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

1

場合によります。コードのブロックが何をするかを説明する大きな適切なパラグラフを作成する場合、他の適切な記述のように、適切に句読点を付けます。OTOH、1行のコードにコメントするだけで、コメントはしません。

どうして?-SMSメッセージで短い文章を使用する一方で、適切な文章を使用してメールを作成する理由と同様です。あるケースでは、適切なテキストブロックを作成するために座っているので、自動的に「適切に実行」しますが、別のケースでは、わかりやすくするための短いメモです。

私のコードからの実際の例:

クイックノートコメント:

// 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.

.NET開発者ですか?;-)
モシェ

@Moshe:Java。これは非常に大きく複雑なアプレットからのコードで、ブラウザで実行されることを除いて基本的にデスクトップSwingアプリに似ています。:)
ボビーテーブル

私はそのMDIは.NET用語だと思っています。
モシェ

@Moshe:いや、それは汎用です(en.wikipedia.org/wiki/Multiple_document_interface)。
ボビーテーブル

1

はい、この方法であなたは良いコーディング規約を作成し、それはまたあなたのコードをレビューする第三者のためにきちんと読めるコードを作成すると思います。


1
二人目はどうですか?
daviewales

0

IntelliSenseおよび生成されたドキュメントで見られると思われるXMLコメントを作成するときは、常に適切に大文字と句読点を使用します。これらははるかに形式的な構造であり、そのように扱われるべきです。

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

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.