コードコメントにタイトルを書きますか？[閉まっている]

私が書いたいくつかの古いコード（大学の1年目）を参照していたときに、コードのさまざまな部分の前にコメントタイトルを書くことに気づきました。のようなもの（これはモノポリーゲームから）：

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

これは冗長であり、コードが非常に明確であれば間違いなく不要かもしれませんが、ファイルをスキャンしてみると、実際のコードをほとんど見ていなくても、何が起こっているのかを知っているように強く感じました。特定の状況でこれが適切であると私は間違いなく見ることができるので、これをしますか？それは良い考えだと思いますか？それとも多すぎますか？

これはコード臭です。これは、なぜではなく、何を言っています。

これが必要な場合は、コードを小さな関数に分割します。

私はいつもそうしています。コードの実行内容をマークすることと、おそらくもっと重要なことですが、あなたが言ったように、コードの塊を簡単にスキャンして見つけることができます。時には、関連するプロセスをコメントに書き留めて、コメントの下にコードを「記入」していきます。

何故多くの人が実際にその理由を明確に述べることができずにその習慣を嫌うのか興味深いと思います。そのようなコメントが眉をひそめている理由は、彼らがあなたが単一の責任原則に違反したサインだからです。その特定の名前は通常、OOコンテキストでのみ使用されますが、一般的な概念は結束とも呼ばれ、他のパラダイムに適用されます。学校は通常、学位プログラムが終了するまで、そのような設計原則を教えません。実際、一部の教師は、すべてを1つのファイルに詰め込んで評価を容易にするために、違反を命じています。したがって、新入生の無知は許されますし、「何か」が間違っていることに気づき、コメントで明確にしようとしたという事実は、状況によっては称賛に値するものです。

私はこれらのことを、コードを明確にするかしないかの方法と考えています。ファイル内のメソッドに基づいて各部分が何であるかを判断できれば、複数のセクションが必要な場合は必要ありません。おそらく、コードファイルが大きくなりすぎた場合は、分解する必要があるため、そのようなコメントの必要性が減る可能性があります。

チーム内で作業して標準を考案すれば、少なくとも同じ方法でコーディングとコメントを作成できるので、コードを見やすくなります。

これは、自分に意図を伝えたり、「ここからデータクリーニングを開始する」などの便利なブックマークを本質的に入れたりすることが多いためです。通常、そのタイトルの下には、私がやっていることの論理とその理由についての短い短い説明があります。

冗長性が好きです。何らかの理由でラボノートを紛失したり、何年も前に書いたコードを再確認したりする必要がある場合、私がやっていることとそれをしている理由をまとめる必要はありません。少なくともそのロジックの一部がコードに含まれている場合、少なくとも再度作業するのに十分なほど文書化されています。

それに対する私の傾向の一部は、私のプログラミングのかなりの部分が本質的に統計的であり、したがって幾分反復的であると思います。検索に役立つ名前の関数を持っているコードがいくつかあるかもしれませんが、一般的な線形モデル関数のようなもののかなり類似した使用法を数十個持っているかもしれません。それらのどれが「選択A対選択BまたはCに対する結果の感度」コードであり、どれが他のものであったかを見つけることができると便利です。それはしばしばタイトルによってスピードアップされます。

これは、膨大な数の関数を含む巨大なソースファイルがあり、そのようなチャンクに大まかに整理できる場合に便利だと思います。しかし、より小さく、より焦点を絞ったソースファイルよりも、それが好きだと言っているわけではありません...