「Clean Code」の本を読んだら、コメントはコードを台無しにするので書くべきではないと書かれています。
しかし一方で、「kohana」コード (多くのコードの 1 つとして) には、コードのほぼすべての行の前に、広範なドキュメントとコメントが含まれています。
将来、ユーザープログラマーが使用するプロジェクトを作成しています...その場合、コメントはどのように記述すればよいですか?
これをより明確にするために-私はすべきですか：
あなたがすべき：
コードのすべての行にコメントを付ける必要はあまりありませんが、そうしないと不明確またはあいまいになるコード行にコメントを付けることをお勧めします。
私はコメントを書かないことを信じています。代わりに、自己コメントするコードを記述します。つまり、関数と変数はそれらが何をするかを説明しているということです。たとえば、次の2つの方法で記述できます。
function foo1($a, $b, $c){
return md5($a . $b . $c);
}
またはあなたは書くことができます
function encryption($pepper, $content, $salt){
return md5($pepper . $content . $salt);
}
この例では、最初の例では何をしているのかわかりませんが、2番目の例では、それが何をしているのかを正確に知っています。コメントが必要だと私が感じるのは、それを行う方法を理解するのに長い時間がかかり、それが何をしているのかがはっきりしない、本当にハッキーなコードを書いた後だけです。ただし、これはかなりの距離にあるはずです。
ドキュメントが適切でない理由は、一般的に発生するのは、関数が最初に作成されたときと、バグの修正とメンテナンスの後で、すばらしいコメントを書くことだからです。コメントは更新されませんでしたが、コメントは関数が実行しないことを示しており、ヘルプではなく混乱をもたらしています。
私は主に次の 2 つのケースでコメント/ドキュメントを書きます。
ほとんどの (すべての) まともな IDE には、コメントを折りたたんだり隠したりするメカニズムがあります。本にそう書いてあったからとか、「めんどくさい」と思ったからといってあきらめないでください。
乱雑は主観的な用語です。コメントを 1 行書くだけで、将来のあなたの頭痛の種を 10 時間節約できると思います。
正直なところ、私は将来の読者を検討します。彼らはコメントから恩恵を受けますか? 私自身の場合、書き損ねたコメントを後悔しただけで、不必要なコメントをしたことはめったにありません。「これを忘れるわけがない…」と何度も思いました。
別の方法として、完全なコメント付きのコードの別のコピーと、ほとんど/すべてのコメントを削除したリリース バージョンを維持することもできます。
コメントを書くべきではないという本を読んでも、すぐに捨てて、永遠に忘れるべきです。あなたがコードを扱う唯一の人であるかどうかは気にしません。それでも、コードを文書化する必要があります。
私にとって、他の開発者が使用するコードに取り組んでいる場合は、PHPDoc (JavaDoc) スタイルのドキュメントに固執するようにします。つまり、すべてのクラス、メソッド、プロパティなどを可能な限り徹底的にドキュメント化します。これがもたらす利点の 1 つは、多くの IDE が実際にこの情報をコード補完に使用するため、アプリケーションの操作がさらに簡単になることです。
コード ブロック自体の中で、すべての行にコメントする必要はないと思います (特に、何をしているのかがすぐにわかる行)。ただし、コードのさまざまなセクション、さまざまなロジック ブランチなどにコメントを付けると便利です。
また、私が提案するコメント以外のことの1つは、目的に意味のある変数名を使用することです（単純なカウンターを除く）。多くの場合、人々はかわいらしくなって、3 文字から 4 文字の変数名を使いたがります。これは、タイプする時間が長くなったり、コードが短くなったりするという見当違いの意見があるためです。product_catalog_iteratorクラスを説明するような長い名前が必要な場合は、私にとってはそれよりも優れているprodcatitか、類似しています。