方法や内容ではなく、理由を説明するコメントの例は何ですか？[閉まっている]

まず、この質問では、ソースコードのコメントが良いか悪いかという論争から離れたいと思います。なぜ、何を、どのようにあなたに伝えるコメントについて話すとき、人々が何を意味するのかをより明確に理解しようとしています。

多くの場合、「コメントは理由を説明する必要があり、コード自体は方法を説明する必要があります」などのガイドラインがあります。抽象レベルで声明に同意するのは簡単です。しかし、人々は通常これを教義のように落とし、それ以上説明することなく部屋を出ます。私はこれが非常に多くの異なる場所や文脈で使用されているのを見て、人々がキャッチフレーズに同意できるように見えますが、彼らは完全に異なることについて話しているようです。

それでは、質問に戻ってください：もしコメントがあなたになぜ言うべきなら、私たちが話しているこの理由は何ですか？これが、そのコードがそもそも存在する理由ですか？これは、そのピースのコードがやるべきことですか？誰かが明確な説明をして、良い例を追加できれば本当にありがたいです（悪い例は実際には必要ありませんが、対比のために自由に追加してください）。

コメントが良いか悪いかについては多くの質問がありますが、なぜあなたに伝えるコメントの良い例が何であるかの特定の質問に対処する人はいません。

最も一般的で最も特徴的な例は、さまざまな回避策に関するコメントです。たとえば、これは：

https://github.com/git/git/blob/master/compat/fopen.c：

/*
 *  The order of the following two lines is important.
 *
 *  FREAD_READS_DIRECTORIES is undefined before including git-compat-util.h
 *  to avoid the redefinition of fopen within git-compat-util.h. This is
 *  necessary since fopen is a macro on some platforms which may be set
 *  based on compiler options. For example, on AIX fopen is set to fopen64
 *  when _LARGE_FILES is defined. The previous technique of merely undefining
 *  fopen after including git-compat-util.h is inadequate in this case.
 */
#undef FREAD_READS_DIRECTORIES
#include "../git-compat-util.h"

GitおよびLinuxのソースには、さらに多くの例があります。両方のプロジェクトがこの規則に従うことを試みます。

また、コミットログを使用してこのルールをさらに厳密に守ることをお勧めします。コードのコメントの場合、コードを修正しても、コメントの更新を忘れることがあります。通常のプロジェクトのコードの量では、遅かれ早かれ起こることが保証されています。一方、コミットログは特定の変更に関連付けられており、バージョン管理システムの「注釈」/「非難」機能を使用して呼び出すことができます。繰り返しますが、GitとLinuxには良い例がいくつかあります。

たとえば、このコミットを見てください。（ここではコピーしません、長すぎます）。それは、正確に何が間違っていたのか、そしてなぜそれが間違っていたのかを説明するほぼ全ページ（そして少し画面上）をとる4つの段落を持ち、すべてのwhoping SIX行を変更します。これらのコメントは、次の2つの目的で使用されます。

1. 送信されたすべての変更がレビューされ、コミットログが変更をレビュー担当者に説明する必要があります。
2. バグが見つかった場合、関連するログは「pickaxe」または「blame」を使用して取得され、以前の不正な動作に戻らないようにします。

（注：gitリポジトリをランダムに参照してこれらの2つの例を思いつくのに、せいぜい10分しかかかりませんでした。

コードの背後にある理由を説明する理由を説明するコメント-例：

// We need to sync the values if the temp <doodad> GUID matches one of the active <doodad>'s
// GUID, as the temp <doodad> has the most recent values according to the server and said 
// values might have changed since we added the <doodad>. We want a user to be able to <foo> 
// the <doodad> whenever, which means those values must be accurate.
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

コードが何をするのかを説明するコメント。

// Loop through our <doodads> and check for a GUID match. If it matches, copy the new values
// on the <doodad> that matches 
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

違いは、メンテナーが最初のものを見て、「ああ、これは時代遅れかもしれない！」と言うことができるということです。2番目のケースでは、メンテナーは、コード自体が明らかにしないことを何も伝えないコメントを持っています（適切な変数名を想定しています）。

ゲートウェイアドレスを取得するために必要な場所（または合理的な推測）に取り組んだiOSコードから、なぜコメントの実際の例を示します。「受信ソケットを初期化する」などのコメントを残しておくこともできますが、それはメンテナ（または将来の私）に何が起こっているのかを伝えるだけであり、最初の場所。

/*
 We're going to do something really hacky here and use a custom partial
 implementation of traceroute to get our gateway IP address.

 [rant removed - irrelevant to the point]

 There's no good way to get at the gateway address of an iDevice
 right now. So, we have two options (per https://devforums.apple.com/message/644915#644915 ):
 1. Get at and parse the routing table (like netstat -rn, or route -n)
 2. Do a traceroute and grab the IP address for the first hop

 As far as I can tell, the former requires <sys/route.h> from the Mac OS X
 header files, which doesn't seem like a good idea to me. Also, there's a
 thread on the Apple Developer forums that seems to imply that header isn't
 in iOS for a reason (https://devforums.apple.com/message/774731#774731 ).

 So when we send our request with a TTL of one it will survive a single hop
 to the router and return, triumphant, with the router's IP address!

 Viva la kludge!

 PS: Original source was the below SO question, but I've modded it since then.
 http://stackoverflow.com/questions/14304581/hops-tracing-ttl-reciveform-on-ios/14304923#14304923
 */

// Default to using Google's DNS address. We used to try checking www.google.com
// if reachability reported we had internet, but that could still hang on routers
// that had no internet connectivity - not sure why.
const char *ip_addr = [kGoogleDNS UTF8String]; // Must be const to avoid undefined behavior
struct sockaddr_in destination,fromAddr;
int recv_sock;
int send_sock;

// ... more code follows

ジェフ・アトウッドのブログ投稿「コードはあなたに方法を教え、コメントはあなたに理由を教えてください」で引用したことから、答えを始めたいと思います。

最高の種類のコメントは、不要なものです

彼は次のようにも述べています。

最初に、松葉杖のようにコメントに頼らずに、コードをできるだけシンプルに理解できるように努力する必要があります。コードを理解しやすくすることができない時点でのみ、コメントの追加を開始してください。

私は完全に同意し、この時点でコードを可能な限り単純化する前に、コードを機能させてリファクタリングを開始することを追加する必要があります。したがって、リファクタリング前の最初の実行中に、コメントが非常に役立つ理由を追加します。

たとえば、2次元のハッシュテーブルで3つのネストされたループを使用してデータを解析している間に平日のテーブルを埋める場合、数週間見られず突然リファクタリングされた場合、誰かまたはあなた自身によって行われたことを追跡するのは非常に簡単です。

[loop1]6oclock -> [loop2]Monday -> [loop3]stage 1 to 4
         -> tuesday-> stage 1 to 4
         ...
         -> Saturday -> stage 1 to 4
    7oclock -> Monday-> stage 1 to 4
        ....etc.

上部は、リファクタリング前に3つのネストされたループがどのように機能するかの例です。
また、いくつかの分岐条件を説明することで、プロセスで考えていたコードをよりよく理解することができます。

// added a zero before the actual day in order for the days always to be 2 digits long.
if( actualDayFuture < 10 ) 
{ 
     actualDayFuture = padIfSingleDigitDate(actualDayFuture); 
}

シンプルで明白なコードでさえ、コメントでうまく機能します。同僚だけでなく、ソフトウェアを保守する上で自分自身にとっても、物事をもう少し明確、明確、または理解しやすくするためです。

確かにxpは自己説明的なコードを持っていると述べていますが、1行のコメントは痛いですか？

また、このブログの次のルールが非常に役立つこともわかっています。

• 書く前に資料を理解する
• 聴衆が4年生のように書く
• 読者があなたを誤解する可能性について考えてください

自分のコードや他の誰か、あるいはレガシーコードに戻らなければならない人は誰でも、それが頭痛の種になることを知っています。だから、怠けたり、何も少しもコメントしないことで超コーダーになろうとするのではなく、引用されたルールに従うことで、あなた自身のコードやあなたのコードを維持しなければならない貧弱なバグを作らないでください。

また、レビュー中に行われた多くのプログラミングの決定は疑われており、コードが長年にわたって使用されたときに見つかった主要なバグのためにプログラムの一部のセクションが重要である場合でも、一部のコードがなぜそのまま書かれたのかが常に明確ではありません。だから、acmqueueからの最後の引用でtl; drを閉じることであなたを完全に退屈させないために：

以前の、明確で、広範囲にわたるドキュメントは、生き残り、適応できるソフトウェアを作成するための重要な要素です。高水準の文書化は、開発時間を短縮し、作業を改善し、収益を改善します。どんなテクニックからでもそれ以上のものを求めるのは難しいです。

特定の機能/コードがより徹底的に説明されている参照、または特定のプログラミング方法が選択された理由を説明する参照へのコメントを減らす傾向があります。

同様のスキルを持つ他のプログラマーがコードを使用または読み取ることを考えると、何かを達成するために予想とは異なる方法を使用する場合はコメントすることが重要です。そのため、この方法を選択した理由をコメントで説明できます。

たとえば、Androidデバイスで2つの異なるセンサーを使用でき、そのうちの1つがニーズに合わない場合、他のセンサーを選択した理由をコメントで説明できます。

だから、「なぜ」与えるべき根拠作ら選択肢のを。

コメントは、コードが何をしていないかを伝える必要があり、必ずしもWHY、HOW、またはWHATによって削除されているわけではありません。適切な名前があり、機能が詳細に記述されている場合、コードで何が起こっているかを正確に伝えることができる可能性は十分にあります。例えば：

List<LightMap> maps = makeLightmaps(receivingModels);
TrianglePartitioner partition = new Octree(castingTriangles);
List<Photon> photons = firePhotons(lights, partition);

if (photons.Count > 0)
{
      PhotonPartitioner photonMap = new KDTree(photons);
      gatherPhotons(maps, photonMap, partition, lights);
}

このコードにはコメントは必要ありません。関数名と型名により、理解しやすくなります。

ただし、場合によっては、上記のような流なコードを実際に作成することは困難または不可能な場合があります。たとえば、次のコードスニペットは、球体上の統計的にランダムなポイントを見つけるためのものです。数学はかなり不透明なので、説明へのリンクを含むコメントは、それがどのように機能するかを伝えるのに役立ちます。これは、伝えるために関数内でラップすることができWHATそうでない場合は、リンクのタイトルは、その部署のに役立ちます、それが複数回必要に応じてコメントを必要とせずに行います。

double randomA = localGenerator.NextDouble();
double randomB = localGenerator.NextDouble();

//http://mathworld.wolfram.com/SpherePointPicking.html
double theta = 2 * Math.PI * randomA;
double phi = Math.Acos(2 * randomB - 1);

Vector3 randomDirection = new Vector3(Settings.ambientRayLength * (float)(Math.Cos(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)(Math.Sin(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)Math.Cos(phi));

コメントがコードに含まれていないことを伝える別の例は、決定を説明するためのものです。次の例では、コードはスレッド化されたコード内の非スレッドローカル変数をロックしません。そここの理由は、コメントは説明WHY。コメントがなければ、バグと見なされるか、気づかないこともあります。

Random random = new Random();
Parallel.For(0, maxPhotons, delegate(int photonIndex, ParallelLoopState state)
{
    ...
    //I don't actually care if this random number is unique between threads, threadsafty is not that big of a deal
    //  in this case and locking the random object could cause a lot of lock contention
    while (random.NextDouble() > reflectProbability)
    {
        ...
    }
    ...
}

おそらく、ランダムオブジェクトが最初に並列ループ内に作成されない理由を説明するために改善される可能性があります。理由がなければ、誰かが一緒に来て、アイデア全体が愚かであり、リファクタリングのための良い場所であることを認識させることもできます。

さまざまな種類の「理由」を認識しておくと便利な場合があります。

• 過度に複雑に思えるコードは、単純化すると機能しません（たとえば、一部の場合にコードが機能するようにするには、一見余分なタイプキャストが必要になる場合があります）。

• 危険なように見える特定の簡単な操作が実際に安全である理由（例えば、「フェッチデータルーチンは、最後を過ぎたダミーアイテムアイテムを他のものよりも小さく、その後のアイテムは大きいと報告します。ソートするアイテム別の前に、一貫した昇順または降順で、少なくとも1つ以上の（おそらくダミーの）アイテムが続きます」）。

多くの場合、コードの一部の2番目のタイプのコメントは、別の1番目のタイプのコメントと「一致」する場合があります（たとえば、「この一連の操作を簡略化できるように見えるが、FitzルーチンはBandersnatchがBlarpedされるまで、WongleはWoozledされません。」）

プログラムを書いている場合は、単にランダムに入力するだけではなく、正式なドキュメントであろうと頭の中であろうと、あなたが望むもののモデルを持っているので、それをしていることを忘れないでください。あなたの頭の中の物は、コンピューターのソフトウェア/データと同じくらいリアルです（そしてバグが含まれている可能性があります）。

コードを読んでいる人はそのモデルを頭に置いていないかもしれないので、コメントはモデルが何であり、コードがどのように関連しているかを伝えるのに役立ちます。それが「理由」の意味だと思います。確かに、コード自体を可能な限り自明なものにするのは良いことですが、それだけでは十分ではありません。例：

// transform the x,y point location to the nearest hexagonal cell location
ix1 = (int)floor(0.5 + x + y/2);
iy1 = (int)floor(0.5 + y);

それに加えて、モデルは時間とともに変化し、それらの変更はコードに転送する必要があります。そのため、コメントには、コードに「理由」が含まれているだけでなく、予想されるモデルの変更に応じてそれを変更する方法も同様に重要である必要があります。例：

// to change to square cell locations, remove the "+ y/2" in the above code

コメントの目的は時々無視されると思います。

すべてのコメントが「理由」タイプではありませんが、多くのコメントがそうです。
これらは1つの（Delphi）ソースファイルの例です。

// For easier access to the custom properties:

function GetPrivate: Integer;   // It's an integer field in the external program so let's treat it like that here

// The below properties depend on the ones above or are calculated fields.
// They are kept up-to-date in the OnEventModified event of the TTSynchronizerStorage
// or in the ClientDataSet.OnCalcFields of the TcxDBSchedulerStorage.DataSource.DataSet
property IsModified       : Boolean   read GetIsModified   write SetIsModified;
property IsCatTT          : Boolean   read GetIsCatTT      write SetIsCatTT;
property IsSynced         : Boolean   read GetIsSynced     write SetIsSynced;

lLeftPos := pos(' - [',ASubject); // Were subject and [shiftnaam:act,project,cust] concatenated with a dash?

// Things that were added behing the ] we will append to the subject:

// In the storage the custom value must also be set for:
Self.SetCustomFieldValueByname(cCustFldIsCatTT,Result);

// When we show the custom fields in a grid, the Getters are not executed,
// because the DevEx code does not know about our class helpers.
// So we have two keep both properties synchronized ourselves:

// lNewMasterEvent was set to usUpdated, overwrite because we added:
if ARepair then
  lNewMasterEvent.CustUpdateStatus := usRecreated

// The source occurrence date may have bee changed. Using GetOriginalDate we can retrieve the original date,
// then use that for creating a target occurrence (and update its date):

lNewTTOccurrence.CustSyncEntryID := cSyncEntryID0;    // Backward compatibility with old sync methode

// Single event became recurring or vice versa; replace entire event

// In contradiction to CopySingleEventToTimeTell, CopyMasterEventToTimeTell does not have a ANewStatus parameter
// because master events are always added.

（私の）ことに注意してください理由（したがって、コロンで終わる）のコメントは、通常はそれをするつもりされたコードの前に。

何が起こっているのかだけを説明するコメントがあります。たとえば、プロセスに論理的なグループ化を含む多くのステップがある場合（そしてコードはそれを自動的に表示するためにリファクタリングされません）、私は次のようにコメントします：

// Step 1. Initialization

なぜそうする必要があるのか​​という事情のために、なぜ奇妙な、または非論理的な方法で何かをするのかという理由としてWHYを理解しています。どのようにコードがない「感覚」を作るていない場合でも、関係なく、それがどのように奇妙な、コード自体に見ることができません。何をおそらく最高クラス/関数のドキュメントの冒頭で語られています。そのため、HOWとWHATに含まれていないものを説明するWHYを追加し、制御できない理由のために必要な独特の方法を追加します。

もちろん、ユニコーンや虹の国以外では、常にそうではありません...

どうやって：

foreach($critters as $creature) {
   $creature->dance();
}

何：

/* Dancing creatures v1.0
 * 
 * The purpose of this is to make all your critters do the funky dance.
 */

foreach($critters as $creature) {
  $creature->dance();
}

なぜ：

// We had to store the items in an array of objects because of _____ (reason)
foreach($critters as $creature) {
   $creature->dance();
}

特に名前が良いヒントを与えても、関数が何をするかが常に明確ではないため、C ++ヘッダーファイルにコメントを書くことを常に学びました。特にAPIを他の開発者に渡すか、doxygenのようなautodocのツールを使用する場合です。

だから私には典型的なコメントは次のようになります

/*** Functionname
/*   What happens here
/*  [in] Params
/*  [out] params
/*** 

私がコメントを使用したのは、「これに触れないでください！」または「行が削除された場合にプログラムがクラッシュする...」など、プログラマにとっても理解しにくいものだけです。

回避策、ハッキング、奇妙な行動は、私の目での基準を満たしています...

非常に良い例でさえも、リチャードという名前の誰かが書いた混乱したコードのこの「回避策」であり、他の誰かがそれをラップし、コメントで理由を説明しました... https://stackoverflow.com/a/184673/979785

残念ながら、「常にそうだった」か、アクセス権がないか、または...まあ、あなたはオリジナルに触れることができないため、ブル****をラップすることを余儀なくされることがかなりありますオリジナルを修正する時間がないため、実際にはオーバーヘッドの対象になりません。

コードは実行計画を指定することになっています。そうすれば、プログラムのフォロワー（またはコンパイラー）は、何をすべきか、そしてそれをどのように行うかを把握できます。プログラムフォロワーが従うことができるステップに分解されるもの。基本的な手順は方法です。

コーダーの意図は別の問題です。シンプルで明確でわかりやすいコードでは、その意図は明らかです。適度に熟練した人間の読者は、コードを読むだけで、コードのブロックの意図に到達します。ほとんどのコードは次のようになります。

時折、意図と計画の関係があいまいになります。このコードは、何がどのように表示されるかを示していますが、その理由は表示されていません。そのとき、その意図を明らかにするコメントに価値があります。プログラマーの意図はその理由です。

現在、この問題は、複雑でやや複雑なデータモデルに対するストアドプロシージャとビューを介して進行しています。

「x.accountがnullでなく、x.addressが（fedexからアドレスを選択する）次にx.account else y.accountが終了する場合」などの選択を（多数）作成し、時間はありませんが生産性が期待されますallは、すべてのソースコードを読み取ります。そして、この種の例は一種の理にかなっていますが、それはまだ不可解です。

fedexでxであり、yでない場合はyである理由を説明するコメントは、システム全体に光を当て、それらを十分に読み取ると取得を開始します。そして、これは単純化されすぎており、数百または数千の同様の声明があります。2007年からの親切な開発者がそれらの理由を入れた人に心から光ります。

そのため、複雑な複雑なデータモデルと毛むくじゃらのビュー、および複数の有効な名前のパスを持つストアドプロシージャがあります。

私はこのコメントを書きました。それは説明の具体的な例だ理由コードの行は、それが何であるかであり、特に、私はそれを変更する理由。

このメソッドは、保存されたデータを調べ、一方が現在まで、もう一方が開始日まで完了しているかどうかを評価します。

// In principal, this should be ">=", as we may have data up to the account start
// date but not complete for that day; in practice, 98% of the time if we have
// data for the start date it *is* complete, and requerying it would be a waste
// of time.
while (endDate > accountStartDate)
    ...

おそらく推測できるように、大なり演算子は以上でした。コメントは、古い値が理にかなっている理由と、新しい値が優れている理由を説明しています。将来これを見ると、「>」の使用は見落としではなく、最適化であることがわかります。その後、その時点での必要性に基づいて、変更または削除できます。