coding-style - コードにコメントすることについての「厳しいルール」は何ですか?

Question

他の質問も見ましたが、このテーマの扱い方にはまだ満足していません。

コード検査でコメントをチェックするために、抽出したもののリストを抽出したいと思います。

お互いに打ち消し合うようなことを言う人もいると思います。でもねえ、キャンプごとにリストを作成できるかもしれません。まったくコメントしない人にとっては、リストは非常に短いものになります:)

score 36 · Accepted Answer

コメントについては、単純なルールが 1 つあります。あなたのコメントは、あなたがそれをしている理由を物語っていなければなりません。

このようにして、私のコードを継承する人は誰でもコードの背後にある意図を理解できるようにします。

score 16 · Accepted Answer

私はパブリック関数または保護された関数にメタコメントを付けてコメントし、覚えていれば通常はプライベート関数にアクセスします。
十分に複雑なコードブロックが存在する理由をコメントします (判断の呼び出し)。その理由が重要な部分です。
最適ではないと思うコードを書いた場合はコメントしますが、よりスマートな方法を見つけられないか、後でリファクタリングすることがわかっているため、そのままにしておきます。
不足している機能や、コードに存在しない今後の要件コード (TODO など) を自分自身や他の人に思い出させるためにコメントします。
クラスまたはコードのチャンクに関連する複雑なビジネスルールを説明するためにコメントします。私は、次の人/ギャルがなぜ私が百行のクラスを書いたのかを知っていることを確認するために、いくつかの段落を書くことで知られています.

score 12 · Accepted Answer

コメントが古い (コードと一致しない) 場合は、削除するか更新してください。不正確なコメントをそのままにしてはいけません。

score 6 · Accepted Answer

ドキュメンテーションはセックスのようなものです。良いときはとてもとても良いし、悪いときは何もしないよりはマシだ

score 6 · Accepted Answer

できるだけ自明の読みやすいコードを記述します。複雑すぎて一目で理解できないコードを書かなければならないときはいつでも、コメントを追加してください。また、将来の保守/リファクタリングを容易にするために、記述したコードの背後にあるビジネス上の目的を説明するコメントを追加します。

score 5 · Accepted Answer

あなたが書いたコメントは、あなたのコードの品質について明らかにすることができます. コード内のコメントを削除して、より適切で明確なコードに置き換えたことは数え切れないほどあります。このために、いくつかのコメント禁止ルールに従います。

コメントが単にコード行を説明するだけの場合は、そのコード行自体に語らせるか、より単純なコンポーネントに分割する必要があります。
コメントが関数内のコードブロックを説明している場合、代わりに新しい関数を説明しているはずです。

これらは、2 つの異なるコンテキストで繰り返される同じルールです。

私が従う他のより一般的なルールは次のとおりです。

動的に型付けされた言語を使用する場合は、重要な関数がその引数について行う期待と、呼び出し元が戻り値に関して行うことができる期待を文書化します。重要な関数は、ローカル以外の呼び出し元を持つ関数です。
ロジックが別のコンポーネントの動作によって決定される場合、そのコンポーネントに対する理解と期待を文書化することをお勧めします。

score 4 · Accepted Answer

RFC やその他のプロトコル仕様を実装する場合は、ステートマシンやイベントハンドラなどに、それらが対応する仕様のセクションを付けてコメントします。後で改訂された場合に備えて、仕様のバージョンまたは日付を必ず記載してください。

score 3 · Accepted Answer

厳格な規則はありません-厳格な規則は教義につながり、人々は一般的に、自分で考えるほど賢くないときに教義に従います。

私が従うガイドライン：

1 /コメントは何が行われているのかを示し、コードはそれがどのように行われているのかを示します-あなたの努力を複製しないでください。

2 /コメントは、各行ではなく、コードのブロックを参照する必要があります。これには、ファイル全体、関数全体、またはコードの複雑なスニペットを説明するコメントが含まれます。

3 / 1年後に戻ってきて、コードとコメントの組み合わせがわからないと思う場合、コメントはまだ十分ではありません。

score 3 · Accepted Answer

私は通常、メソッドを書く前にコメントします。関数内で実行する必要がある各ステップに対して 1 ～ 2 行のコメントを記述し、コメントの間にコードを記述します。完了したら、コードは既にコメントされています。

これについての重要な点は、コードを書く前にコメントが付けられていることです。そのため、コメントの以前の知識について不当な仮定はありません。私自身、自分のコードを書いたとき、自分のコードについて何も知りませんでした。これは、当然のことながら、理解しやすい傾向があることを意味します。

score 2 · Accepted Answer

私は悪いコメントに関する完全な記事を書きました。楽しみ：）

コードでどのように悪いコメントが生まれるか

score 2 · Accepted Answer

コメントに関する優れたルール: 何かを理解しようとしてコードを読んでいて、どこかのコメントで答えが得られる場合は、答えがわかっているときにそこにコメントを入れてください。

その時間を調査に費やすのは1 回だけです。

最終的には、ガイドを残す必要がある場所と、単独で十分に明白な場所を書きながら知ることができます。それまでは、コードを調べて、なぜ何かをしたのかを理解しようとします :)

score 1 · Accepted Answer

ヘッダーのドキュメント（またはメソッド宣言の前にあるブロックと呼ぶもの）をチェックするときにチェックする非常に重要なことは、ディレクティブと警告を簡単に見つけられることです。

ディレクティブは、クライアントに影響を与える「実行」または「実行しない」命令です。UIスレッドから呼び出さない、パフォーマンスが重要なコードで使用しない、Yの前にXを呼び出す、使用後に戻り値を解放するなどです。

警告は、厄介な驚きになる可能性のあるものです。残りのアクションアイテム、既知の仮定と制限などです。

作成および検査しているメソッドに焦点を合わせると、すべてが表示されます。プログラマーがあなたのメソッドと他の30人を1時間で使用している場合、完全な読み取りを期待することはできません。興味のある方は、その研究データをお送りします。

score 1 · Accepted Answer

理由に焦点を当てます。多くの場合、読みやすいものだからです。TODOも素晴らしいです、彼らは多くの時間を節約します。

そして、私はインターフェース（例えばファイル形式）を文書化します。

score 1 · Accepted Answer

コードの先頭にコメントブロックを作成し、プログラムの目的、作成日、ライセンス/著作権情報 (GPL など)、およびバージョン履歴をリストします。

インポートする理由が明らかでない場合、特にプログラム全体でインポートが必要ないように思われる場合は、インポートにコメントすることがよくあります。

各クラス、メソッド、または関数に docstring を追加し、そのブロックの目的と、必要と思われる追加情報を説明します。

通常、関連するセクション (ウィジェットの作成、変数など) には境界線があります。プログラミング環境に SPE を使用しているため、これらのセクションが自動的に強調表示され、ナビゲーションが容易になります。

コーディング中のリマインダーとして TODO コメントを追加します。コードが正しく動作することが確認されたら、コードをリファクタリングすることを思い出す良い方法です。

最後に、明確化が必要な行や、将来の自分や他のプログラマーのために何らかのメタデータが必要な行についてコメントします。

個人的には、コードを見て、それが何をすべきかを理解しようとするのが嫌いです。誰かがそれを説明する簡単な文章を書くことができれば、人生は楽になります. 私の本では、自己文書化コードは誤称です。

score 1 · Accepted Answer

クラス内のすべてのクラス、すべての関数、すべての変数を文書化します。単純な DocBlocks は前進する方法です。

通常、これらの docblock は、何よりも自動化された API ドキュメント用に作成します...

たとえば、私の PHP クラスの 1 つの最初のセクション

/**
 * Class to clean variables
 *
 * @package     Majyk
 * @author      Martin Meredith <martin@sourceguru.net>
 * @licence     GPL (v2 or later)
 * @copyright   Copyright (c) 2008 Martin Meredith <martin@sourceguru.net>
 * @version     0.1
 */
class Majyk_Filter
{
    /**
     * Class Constants for Cleaning Types
     */
    const Integer            = 1;
    const PositiveInteger    = 2;
    const String             = 3;
    const NoHTML             = 4;
    const DBEscapeString     = 5;
    const NotNegativeInteger = 6;

    /**
     * Do the cleaning
     *
     * @param   integer Type of Cleaning (as defined by constants)
     * @param   mixed   Value to be cleaned
     *
     * @return  mixed   Cleaned Variable
     *
     */

ただし、重要なコードをドキュメント化することもあります (init.php から)。

// Register the Auto-Loader
spl_autoload_register("majyk_autoload");

// Add an Exception Handler.
set_exception_handler(array('Majyk_ExceptionHandler', 'handle_exception'));

// Turn Errors into Exceptions
set_error_handler(array('Majyk_ExceptionHandler', 'error_to_exception'), E_ALL);

// Add the generic Auto-Loader to the auto-loader stack
spl_autoload_register("spl_autoload");

そして、何かが特定の方法で何かを行う理由が自明でない場合は、次のようにコメントします。

score 1 · Accepted Answer

私がコメントを残す唯一の保証された場所: TODOセクション。やり直しが必要なものを追跡するのに最適な場所は、コード内にあります。

score 0 · Accepted Answer

コメントに関する記事をここに書きました（実際、私はいくつか行いました）：http: //agileinaflash.blogspot.com/2009/04/rules-for-commenting.html

それは本当に簡単です：コメントはコードができないことをあなたに伝えるために書かれています。

これにより、プロセスは単純になります。-最初に必要なコメントを書き込みます。-コメントが冗長になるようにコードを改善します-冗長になったコメントを削除します。-冗長なコメントがないコードのみをコミットする

score 0 · Accepted Answer

私が行っていることを要約したコードのブロックに1つのコメントを追加します。これは、特定の機能やコードのセクションを探している人に役立ちます。

一見理解できない複雑なアルゴリズムやプロセスについてコメントします。

コードに署名します。

score 0 · Accepted Answer

私の意見では、TODO / TBD / FIXMEなどは現在作業中のコードで問題ありませんが、5年間触れられておらず、それらでいっぱいのコードを見ると、かなりきれいであることがわかります。物事が修正されることを確認するお粗末な方法。つまり、コメント内のTODOノートはそこにとどまる傾向があります。ある時点で修正する必要があるものがある場合は、バグトラッカーを使用することをお勧めします。

Hudson（CIサーバー）には、TODOをスキャンし、コードにいくつあるかを記録する優れたプラグインがあります。しきい値が多すぎる場合は、しきい値を設定してビルドを不安定として分類することもできます。

コメントに関する私の経験則は次のとおりです。コードとコメントが一致しない場合は、両方が正しくない可能性があります

score 0 · Accepted Answer

プリアンブルのみ。クラスの単一の責任、メモまたはコメント、および変更ログを記載します。メソッドに関しては、メソッドにかなりのコメントが必要な場合は、リファクタリングする時期です。

score 0 · Accepted Answer

コメントを書いているときは、立ち止まって反省し、コメントが不要になるようにコードを変更できないか自問してください。わかりやすくするために、いくつかの変数、クラス、またはメソッドの名前を変更できますか? いくつかassertの s またはその他のエラーチェックは、あなたの意図や期待を体系化しますか? コードのいくつかの長いセクションを、明確な名前のメソッドまたは関数に分割していただけますか? コメントは、多くの場合、(a-hem、コード) を明確に書くことができないことを反映しています。コンピューター言語で明確に書くことは必ずしも容易ではありませんが、試してみるには時間がかかります...コードは決して嘘をつかないからです。

PS「厳格なルール」の周りに引用符を使用しているという事実は、それを物語っています。適用されないルールは「厳格なルール」ではなく、適用される唯一のルールはコード内にあります。

coding-style - コードにコメントすることについての「厳しいルール」は何ですか?

22 に答える 22

Related

Reference