web-dev-qa-db-ja.com

1つの中心的な詳細コメント、またはいくつかの小さいコメントのどちらが良いですか？

質問を述べると、どちらが良いですか、1つの中心的な詳細コメント、またはいくつかの小さな「振りかける」ですか。

シーンをセットアップしている間、我慢してください。

キューの実装から値をポップするための次の関数があります。

int queue_pop(queue *list, void **pValue);

Cに精通している場合は、この関数を次のように呼び出すことを理解しています。

struct foo *pFoo;
int rc;
rc = queue_pop(g_FooList, &pFoo);

あなたはこれを手に入れます：

gcc: warning-incompatible pointer type passing 'foo **' to parameter of type 'void **'

さて、このように、この関数をこのように呼び出すことは完全に安全です。関数は、間接参照されたポインターをvoid *以外のものとしてアドレス指定することはありません。メモリーの割り当てとコピーは、任意のキューで定義されている要素サイズに厳密に基づいて行われます。しかし、警告を回避するために、私は次のように呼び出します。

rc = queue_pop(g_FooList, (void**)&pFoo);

これもCで厳密に移植可能ではありませんが、この場合も完全に安全です。しかし、関数の引数をキャストすることはCではほとんど必要なく、実際にはほとんど常にエラーをカバーしているため、次のようにすべての関数でこのタイプの最初の呼び出しを文書化します。

/* Explicit cast - see comments on queue_pop function in queue.c */
rc = queue_pop(g_FooList, (void**)&pFoo);

そうすれば、コードを読んだ人なら誰でもqueue.cファイルを開いて、これが問題ない理由の詳細な説明を読むことができ、心配する必要はありません。そして、彼らはそれをしないので、少なくとも彼らはそれが故意に行われたことを知っており、それには理由があります。

Somoneがキャストを取り除くことを提案しているため、疑問が生じます。これは非常に珍しいためです。具体的なポインター型で関数を呼び出すだけです。次に、ソースファイルの上部にある#pragma Pushで警告を抑制し、抑制を説明するプラグマに詳細なコメントを付けます。コードベースは最終的にはオープンソースになるため、ソースコードのコメント（ヘッダーファイルのコメントではなく）は通常よりも多くの読者を持つことになるので、そのように編成されます。

そもそも私が警告を抑制するのがあまり好きでないという事実は別として（愚かなMSVCの警告を除いて）、それは私の経験でした：

  • A）人々は読まない
  • B）誰かに何かを読んでもらいたい場合は、それを彼らの眼球の前に貼り付ける方がよい
  • C）Aを参照

さて、commentsタグは「ベストプラクティス」についての質問だと言っていますが、これは「意見」に少し遠すぎる傾向があるかもしれません。その場合は、いくつかの反対票を掛けてください。質問は削除します。

[〜＃〜] edit [〜＃〜]私はこれを見た question ですが、コメントを一切使用しないかどうか。ここでは問題ではありません。私は間違いなくある種のコメントを使用します。

copen-sourcecomments
4
Mark Benningfield

サイドノードとして、マクロを定義できます。

    /* pop_macro is used to avoid the incompatible type compiler warning */ 
    #define pop_macro(FooList,Foo) queue_pop(FooList, (void**)Foo)

とは対照的に：

    queue_pop(g_FooList, (void**)&pFoo)

それは次のようになります：

    pop_macro(g_FooList, &pFoo)

コンパイラの警告が消え、他の人が見つけられるコメントを書くための単一の場所があります。

1
Robert Baron

答えは：他のプログラマーが読むもの。

一般に：

人間は注目の幅が短く、すでに読んでいる行のコメントは注目される傾向があるので、振りかけたコメントはもっと読まれるでしょう。コメントを検索することはめったにありませんが、必要なときに気づくだけかもしれません。 すでに存在することを知っているであり、それほど難しくないである場合にのみ、それを読み取ります。

中央コメントが読まれる主な時間は、コードレビューの間です。これは、特定の編集/分岐/機能のレビューをより簡単かつ簡単にすることができるため、非常に役立ちます。その後、コード全体でその中央コメントを参照して、スプリンクルをバックアップできます。

また、ヘッダーファイル内の関数の説明など、ユーザーが設定した標準は、慣れていれば、他のプログラマーが期待したり望んだりする可能性があります。

最後に、ほとんどのプログラマーはすべてのコメントを読むわけではありません、特に、ドキュメントを読んだり、コードベース全体を閲覧したりする前に時間を割いていないオープンソースの世界では特にそうです。より大きな説明への短い参照であっても、少なくともあなたの目の前にの情報を持っていることをお勧めします説明があり、これはいくつかではありませんでした間違い。

より具体的にあなたの例に：

コードでコンパイラの警告/エラーを解決できる場合は、それを行う必要があります。どのようにしているかを説明しますが、コンパイラ設定ではコードで解決ではありません。誰かが別のコンパイラーをいつか配線したいと思うかもしれませんし、あなたのすべての#pragmaを持っていることは時間の無駄かもしれません。そのように、短いコメントは素晴らしいものです。

3
Erdrik Ironrose

呼び出すたびにコードコメントを付けることの欠点は、非常に多くのコメントがあり、ユーザーがそれらを無視し始めることです。 my_queue_pop(g_FooList, &pFoo);のように呼び出し、それ自体がqueue_pop(g_FooList, (void**)&pFoo);を呼び出す関数の作成を検討してください。次に、コメントをmy_queue_popの定義内に配置します。そうすれば、読者は関数の名前を見ただけで理解できます。

2
Max

受け入れられた答えは、私の最初のアプローチとほぼ一致しています。これはおそらく必要に応じてソースから構築されるオープンソースのコードベースになる予定なので、@ Robert Harveyのアドバイスを参考にして警告を残し、エンドユーザーが気になる場合はそれについて心配させることができますそれらだけ。

私はそれだけをやりたくてたまらないだけで、結局はブーメランになってしまうことを知っています。受け入れられた回答に記載されているように、彼らはそれを調べず、警告が偽物であることを確認します-彼らは問題チケットを提出するだけです。彼らは、警告が適用されない旨のプロジェクトドキュメントの通知を確認しません。問題チケットを提出するだけです。

そして、彼らはおそらくソースコードを読まない可能性が高いので、ポインターキャストの周りに散りばめられたいくつかの1行コメントは、ハックルを発生させません。

ですので、注意してください：現実的には、ソースコードに目を見張ることはほとんどないので、悲しみが発生する可能性が低い場所で悲しみを予想しないでください。

[〜＃〜] edit [〜＃〜]これは完全に説得力のある立場だとまだ思っていますが、誰かが実際に問題を解決したため、受け入れられた回答を変更する必要がありました。

提案されたマクロをキューの実装で直接定義することにより、不確実性はソースで解決され、解決のポイントで説明されます。

1
Mark Benningfield