更新
強調のための引用符での私の応答：
コメントはコーディング基準で扱われるべきではなく、それと戦うための一連の防御的な質問をリストするべきであると答えるのが唯一の正しい答えであると私は信じています。
ここでの問題は、コーディング標準がまさにその標準であることです。非常に主観的なアイデアは、コーディング標準に含まれるべきではありません。ベストプラクティスガイドに記載されている場合もありますが、コードレビュー中に開発者に対して使用することはできません。私の意見では、コーディング標準はできる限り自動化に近いものでなければなりません。コードレビューでは、すべてを自動化できる場合、命名、間隔、タブ、ブラケット、コメントなどについて議論するのに多くの時間が無駄になります。さらには約解答して自動化することができます。LINT'ersは、辞書、概念ごとの大文字チェック（変数、関数、メソッド、クラスなど）を許可します。tableschairs
プルリクエストが受け入れられる前に、JavaDocチェックでさえロボットLINT'erによって実装できます。多くのオープンソースプロジェクトがこれを正確に行っています。プルリクエストを送信すると、コードは静的分析を含むTravis-CIファイルで構築され、客観的に表現できるすべてのコーディング標準に合格する必要があります。「間違ってやる」ことや、コメントで「価値を提供すること」、または変数に名前を付ける間違った方法などについての人間の発言はありません。これらの議論は価値がなく、私たちの感情的なコーディングの矢面に立つことができるサードパーティのロボットに任せるのが最善です。
この質問に実際に答えるには、次の質問に答える方法に対処する標準の作成方法に対処する必要があります。このコメントは価値を提供しましたか？コーディング標準では、コメントの「値」を指示することはできません。そのため、人間がそのチェックリストを通過することが必要になります。コーディング標準でコメントに言及するだけで、元のポスターが避けたいチェックリストが作成されます。
そのため、通常、コメントはコンパイラによって処理されず、削除されます。それらの値を決定することはできません。問題のコメントは価値があります。はい、もしくは、いいえ？。この質問に答えることはNP困難です。人間だけが適切に答えるチャンスを持ち、それでも、それを読んでいる人によって、それを読んでいるときにしか答えられません。そのコメントの価値は、天気、彼または彼女の家庭生活、彼らがちょうど出席したばかりの最後の会議、時間、彼らが持っていたコーヒーの量に影響されます。私はこの状況がより明確になっていると信じています。
どのように標準で適切に表現できるのでしょうか？標準は、一貫して公平に適用できる場合を除き、有用ではありません。公正とは、感情的ではなく客観性に関するものです。
私は、コーディング標準が可能な限り客観的であり続けるべきであることを争います。変数がIS目的と命名される方法。適切なスペル、文法構造、大文字と小文字の区別を辞書で簡単に確認できます。それを超えるものは、「おしっこ試合」であり、最も権力のある人または「眉をbeる」ことによって勝ち取られます。私は個人的に、やっていないことに苦労しています。
私がコメントするとき、私はいつも第三者に自分の将来の自分と話すことをコメントします。5年後にこのコードに戻ったら、何を知る必要がありますか？何が役立つのか、何が混乱するのか、何がコードの時代遅れになるのか？検索可能なパブリックAPIを生成するコードのドキュメント化と、未知のサードパーティに価値を提供するコメントコード（そのサードパーティが自分自身であっても）には違いがあります。
これが良いリトマス試験です。あなたがプロジェクトの唯一の人だった場合。自分がプロジェクトの唯一の人になることは知っていました。あなたのコーディング標準には何がありますか？あなたのコードは、クリーンで、自明で、将来自分で理解できるようにしたいと思うでしょう。すべての行にコメントを付けなかった理由について、自分自身でコードをレビューしますか？チェックインした100個のファイルについて作成したすべてのコメントを確認しますか？そうでない場合、なぜ他の人を強制するのですか？
これらの議論で見落とされていると思うのは、Future Youがこのプロジェクトの開発者でもあるということです。価値について尋ねるとき、明日はあなたもコメントから価値を引き出すことができる人です。私の意見では、チームの規模は問題ではありません。チームの経験は重要ではなく、頻繁に変更されます。
これをレビューするコメントコードは、ペースメーカーが患者をクラッシュさせたり殺したりするのを止めることはありません。コードに影響するコメントについて話したら、コメントではなくコードについて話しています。誰かを殺すためのコメントが欠けているだけなら、その過程で何か臭いがする。
このタイプの厳密なコーディング方法のソリューションは、ソフトウェア自体を記述するための方法論としてすでに提供されています。そして、それはコメントとは何の関係もありません。コメントの問題は、製品が最終的に機能する方法に影響がないことです。世界で最も優れたコメントは、ペースメーカーに組み込まれたときにソフトウェアがクラッシュするのを防ぐことはできません。または、ポータブルEKGで電気信号を測定する場合。
2種類のコメントがあります。
機械可読コメント
Javadoc、JSDoc、Doxygenなどのコメントスタイルは、コードセットが提供するパブリックインターフェースにコメントするすべての方法です。このインターフェイスは、他の1人の開発者（2人のチームの専有コード）、不明な数の開発者（JMSなど）、または部門全体でのみ使用できます。このコードは、自動化されたプロセスで読み取ることができます。自動化されたプロセスは、コメント、ala HTML、PDFなどのさまざまな読み取り方法を生成します。
このタイプのコメントは、標準を簡単に作成できます。これは、すべてのパブリックに呼び出し可能なメソッド、関数、クラスに必要なコメントが含まれることを保証する客観的なプロセスになります。ヘッダー、パラメーター、説明など el。これは、別のチームがコードを簡単に見つけて使用できるようにするためです。
私はクレイジーに見える何かをしているが、実際にはそうではない
これらのコメントは、このコードが特定の方法で作成された理由を他者が理解できるようにするためのものです。おそらく、コードが実行されているプロセッサに数値エラーがあり、常に切り捨てられますが、開発者は通常、切り上げられるコードを処理します。したがって、コードに触れる開発者は、現在のコンテキストが通常何をしているのかを理解するためにコメントするのが普通ですが、実際には意図的にそのように書かれています。
このタイプのコードは、非常に多くの問題を引き起こすものです。通常、コメントは解除され、後に新しい開発者によって発見され、「修正」されます。したがって、すべてを壊します。それでも、コメントは、実際に何かを壊すことを妨げない理由を説明するためのものです。
コメントは信頼できません
コメントは最終的には役に立たず、信頼できません。コメントは通常、プログラムの実行方法を変更しません。そして、もしそうなら、あなたのプロセスはより多くの問題を引き起こしているはずです。コメントは後から付け加えられたものであり、決して他のものにはなり得ません。重要なのはコードだけです。コンピューターで処理されるのはそれだけです。
これは恐らく聞こえるかもしれませんが、私は耐えます。これらの2行のうち、本当に重要なのはどれですか？
// We don't divide by 0 in order to stop crashes.
return 1 / n;
この例で重要なのは、 'n'が何であるかわからないこと、nが0であるかどうかのチェックがないこと、そしてたとえあったとしても、開発者n = 0が0のチェックを行った後に停止するものがないことです。役に立たず、これを自動化できるものはありません。これをキャッチできる標準はありません。このコメントは、（一部の人にとっては）かなり美しいものの、製品の結果には関係ありません。
テスト駆動開発
製品にどのような結果がありますか？書かれているコードが文字通り誰かを救ったり殺したりできる業界は、厳密にチェックする必要があります。これは、コードレビュー、コードレビュー、テスト、テスト、コードレビュー、単体テスト、統合テスト、トライアル、ステージング、テストの月数、コードレビュー、およびシングルパーソントライアル、ステージング、コードレビュー、テスト、そしておそらく最終的に行われます生産に入る。コメントはこれとは関係ありません。
コメントがなく、仕様があり、仕様を検証する単体テストがあり、本番デバイスでコードを実行した結果の調査があり、テストされていない、または比較するものがないコードが十分に文書化されているコードコードに対して。
ドキュメンテーションは、誰かが特定の方法で何かをした理由を理解しようとしているときに便利ですが、長年にわたって、ドキュメンテーションは通常、「賢い」何かが実際に必要ではなかった理由を説明するために使用されることがわかりましたそのように書かれています。
結論
すべての行をコメントする必要がある会社で働いている場合、プロジェクトの少なくとも2人のソフトウェアエンジニアが、行が何をしているのかの一般的なアイデアを決定するPerl、Lisp、またはPythonの自動ドキュメントプログラムを既に作成していることを保証します、その行の上にコメントを追加します。これは可能であるため、コメントは無意味です。これらのスクリプトを作成したエンジニアを見つけて、コードを自動的に文書化し、「すべての行のコメント」が時間を浪費し、価値を提供せず、潜在的に損害を与える理由の証拠として使用します。
余談ですが、私は親しい友人のプログラミングの割り当てを手伝っていました。彼の教師は、すべての行を文書化する必要があるという要件を設定していました。ですから、この思考プロセスがどこから来たのかがわかります。何をしようとしているのか自問してください、これは正しいことですか？その後、自問してください。このプロセスでシステムを「ゲーム」する方法はありますか？ある場合、それは本当に価値を追加していますか？コードが特定の仕様を満たしていることをテストする単体テストを自動的に作成することはできません。可能であれば、それは悪いことではありません。
デバイスが人間の内部にあるために特定の条件下で動作する必要がある場合、デバイスが殺されないことを保証する唯一の方法は、長年のテスト、ピアレビュー、トライアル、そしてコードの変更を二度としないことです。これが、NASAがそのような古いハードウェアとソフトウェアをまだ使用している理由です。生死に関しては、「少し変更してチェックインする」だけではありません。
コメントは命を救うこととは関係ありません。コメントは人間に対するものであり、人間はコメントを書くときでも間違いを犯します。人間を信用しないでください。エルゴ、コメントを信用しないでください。コメントはあなたの解決策ではありません。