明確にするためのコーディング標準：コードのすべての行にコメントを付けますか？
私は、生命に関わるソフトウェアを製造するショップで働いており、コードを読みやすくし、潜在的に命を救うことを意図したコメント規則を扱ってきました。私の経験では、要件はチェックリストにチェックされて頭を悩ませる面倒になり、理解しやすいコードを書くことに集中するのに役立ちません。また、コードを理解しやすくする方法について、ピアレビュアーが私とより有意義な会話をするのを妨げます。
また、コメントのない生徒のコードを採点し、それらを無視するためにマークダウンする必要がある理由を確認しました。
適切な名前を使用し、構造をシンプルに保ち、関数を短くし、モジュールに焦点を当てることで、コードを十分に理解できるため、コメントを最小限に抑えることができることを理解しています。
また、コメントがコードがなぜそれを行うのかではなく、なぜそれを行うのかを説明する必要があることも理解しています。
このすべてを考えると、このアイデアを捉えた優れたコーディング標準を作成することさえ可能ですか？ピアレビューに関連するものの、「42行目にコメントするのを忘れた」というメモを生成する、無頓着なチェックリストアクティビティにはならないもの。
このルールがチェックリストの行として扱われる場合に必要となる可能性のあるコードの例：
/* Display an error message */
function display_error_message( $error_message )
{
/* Display the error message */
echo $error_message;
/* Exit the application */
exit();
}
/* -------------------------------------------------------------------- */
/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
/* Display an error message */
display_error_message( 'Error: Configuration file not found. Application has stopped');
}
これを標準ドキュメントで適切に表現することが可能であり、それが単にそうではない場合、これらの線に沿ってアイデアをキャプチャしたいと思います。
コードのすべての行、シーケンス、ステートメント、セクション、構造、関数、メソッド、クラス、パッケージ、コンポーネントなどのコメントを検討してください。次に、名前を変更して単純化し、そのコメントを削除して削除できるようにすることを検討します。コメントはまれですが、チェックインしてください。締め切りまで繰り返します。その後、もう少し繰り返します
マイケルデュラントの答えは私見では悪くありませんが、文字通り質問に答えているわけではないので（彼が自分で認めたように）、次のような答えを出そうとします。
また、コメントがコードがなぜそれを行うのかではなく、なぜそれを行うのかを説明する必要があることも理解しています。
このすべてを考えると、このアイデアを捉えた優れたコーディング標準を作成することさえ可能ですか？
明らかに、次のような質問を含むコードレビューのチェックリストを書くことができます
- 「コメントがある場合、それはなぜコードがそれが何をするのかを説明していますか？」
- 「コードの各行は、そのコンテキストで、コメントを必要としないほど自明であるか、そうでない場合は、そのギャップを埋めるコメントが付いていますか？または（できれば）コードを変更して、コメントはもう必要ないのですか？」
必要に応じて、これを「コーディング標準」と呼ぶことができます（コーディング標準という用語を頭の悪いルールのリスト用に予約する必要があると思われる場合は、ルールが満たされているかどうかに応じて簡単に、コードのフォーマット変数のように、またはどこに宣言する必要があります）。 意味論的な質問にチェックリストの焦点を合わせるのを妨げるものはなく、簡単なルートに行き、formalルールがそれに含まれます。
結局のところ、チームがそのようなチェックリストを必要としていることを確認する必要があります。そのような質問を適用するには、レビュアーとしての経験を持つプログラマーが必要であり、それが専門家チームのコードの可読性を本当に改善するかどうかを見つける必要があります。しかし、それはチームと一緒に考えなければならないことです。
lessの明快さで低品質のコードにつながる主要なアンチパターン
読者の皆さん、タイトルはもともと「コードのすべての行をコメントしましたか？」私も含めて、私たちの多くの本能的な反応を想像できます。後で、より正確なタイトルにタイトルを変更しました。
最初に、私が思った質問を読んで、コメントの内容を重複させますが、複数の人によるレビューに十分な制限がある場合はそうかもしれませんが、その後、繰り返します：人々は間違いを犯し、不一致などに気づきませんでした。最終的には違いが生じます。振り返ってみると、問題ははるかに大きいと思います：
開発者はより悪いコードを書く傾向があります。 「コメントで説明されている-参照してください！」という理由から、よりわかりにくい名前と構造が使用されます。
考慮してください：
living_room_set = tables + chairs.
今検討してください：
set = tbls+chrs # Make the set equal to the table plus the chairs
あなたはもっと不可解な名前と読むべきものの両方を持っているだけでなく、前後を見て、コードを見て、セットとは何ですか？コードを左に見て、コメントを右に見て、tblとは何か、コードを左に見て、コメントを右に見て、chrとは何か、コメントを右に見てください。ユッチ！
概要
開発者として現在の立場に置かれることを余儀なくされた場合（以前のCOBOLプログラミングとして、私は確かに大きなものを見てきました！）、コメントに対する反対を主張するために多くの時間、エネルギー、情熱を費やした場合、コメント標準を開発または強化します。引数を使用したパターン：
コードとコメントが1つだけ変更されると、互いに同期しなくなります
コメントは、ある人の考えを説明しているかもしれませんが、間違っている可能性があるため、バグを隠しています。
コードが読みにくくなる
良いコードは書くのが難しくなります
より不可解な名前を使用する傾向
コードとコメントで読み取るには文字が多すぎる
異なるエディターは異なるスタイルを使用します
コーディングだけではなく、より高い英語能力が必要です
時間とリソースを取り、長期的な価値から差し引く*
さらに、そのようなコメントのないbetterコードを主張してください。実際には標準があります（！）-すべての変数名はfull_english_wordsでなければなりません-1つあります！したがって、よく書かれたコードとテストの標準に向けて、その「標準」エネルギーを使用してください。
2つの難しい問題の1つは、名前の付け方です。コメントで問題をスキップしないでください。
他の問題の1つが時期尚早な最適化であり、最適化が一般に「なぜこのように」コードを不明瞭にする可能性があることを考えると、これは明らかに不十分なコードの説明コメントが有益である可能性がある1つの領域ですが、上記の警告はまだ適用されます。
*明日コード
私はコーディング標準文書がすでに常識を特定する場所ではないと思います。コーディング標準の目的は、合理的な人々が反対する可能性があり、明確な正解が1つもない問題について、一貫性を保証する（そして議論を避ける）ことです。命名規則、インデントなど.
あなたの例のようなコメントは客観的に役に立たず、経験の浅い開発者、またはコメントの存在を機械的にチェックするビルドシステムを使用していた開発者が原因である可能性があります（本当に悪い考えですが、存在します）。どちらの場合も、解決策は教育であり、おそらくコードレビューを通じてです。
あらゆる種類の「ベストプラクティス」をコーディング標準に追加し始めると、すでに複数の本で述べられていることを繰り返すだけです。問題の開発者に「クリーンコード」、「コードコンプリート」、「The Pragmatic Programmer」を購入して、コーディング標準を無駄にしないでください。
それは不可能。あなたが本質的にしようとしていることは、良い判断を機械化することです。
生命維持医療システムなどの重要なソフトウェアを作成する場合、膨大な量のチェックリストなどは事実上避けられません。賢い人でさえミスをするだけでなく、これらのデバイスのソフトウェアの多くは仕事があまり得意でない人によって書かれているため、「システム」はずさんな仕事から身を守り、安全にする必要があります。市場性の費用。
あなたの最良の選択肢は、コメントのための厳密なコーディング標準を省き、例によってチームをリードすることです。適切にコメントされた良質のコードを作成するために努力して、良いコメントがどのようなものかを示します。コメントの書き方を説明する究極の方法を見つける代わりに（それ自体は判断の呼び出しよりも多い）、自分のコードレビューで日常的に自分が何を意味するかを他の人に示します。他のメンバーがあなたのコードを読むとき、彼らがそれが有用だと感じた場合、彼らはそれに追随します。そして、それができない場合、スタンダードは、最初からより良いコメントを書くのに役立ちません。
更新
強調のための引用での私の応答：
私の考えでは、コーディング標準ではコメントに対処すべきではないことを述べ、それと戦うための防御的な質問のリストを提示するのが唯一の正しい答えです。
ここでの問題は、コーディング標準が標準であるということです。非常に主観的なアイデアはnotCoding Standardである必要があります。これはベストプラクティスガイドの一部になる可能性がありますが、コードレビュー中に開発者に対して使用することはできません。私の個人的な意見では、コーディング標準はできるだけ自動化されたものに近いはずです。すべてを自動化できる場合、コードレビューで名前、間隔、タブ、ブラケット、コメントなどについて議論するのに非常に多くの時間を費やしています。
tablesおよびchairsに関する答えでさえ、自動化できます。 LINT'ersは、辞書、概念ごとの大文字化チェック（変数、関数、メソッド、クラスなど）を許可します。プルリクエストが受け入れられる前に、JavaDocチェックもRobot LINT'erによって実装できます。多くのオープンソースプロジェクトがこれとまったく同じことを行っています。プルリクエストを送信すると、コードは静的分析を含むTravis-CIファイルで構築され、客観的に表現できるすべてのコーディング標準に合格する必要があります。コメントで「誤って行う」、「値を提供しない」、または変数に名前を付ける誤った方法などについては、人間のチャイムはありませんそれらの議論は価値を提供せず、感情的なコーディングの矢面に立つことができるサードパーティのロボットに任せるのが最善です。
この質問に実際に回答するには、次の質問への回答方法を示すStandardの記述方法に対処する必要があります：このコメントは価値を提供しましたか？コーディング標準ではできませんおそらくコメントの「値」を指示します。そのため、人間がそのチェックリストを通過する必要があります。 コーディング標準でコメントに言及するだけで、元の投稿者が避けたいチェックリストが作成されます。
そのため、コメントは通常コンパイラによって処理されず、取り除かれます。それらの値は決定できません。問題のコメントは貴重です。はい、もしくは、いいえ？。 この質問への回答はNP困難です。人間だけが適切に回答するチャンスがあり、それでも、それを読んでいる人は、読んだときにしか回答できません。そのコメントの価値が、天候、彼または彼女の家庭生活、彼らが出席したばかりで最後がうまくいかなかった最後の会議、時間帯、彼らが持っていたコーヒーの量に影響される場合。絵がはっきりしていると思います。
どのようにして標準で適切に表現できるでしょうか？公正は感情的ではなく客観性がより重要であり、一貫して公正に適用できる場合を除いて、標準は役に立ちません。
私は、コーディング標準をできるだけ客観的なままにすべきだと主張しています。変数の名前の付け方IS目的。それらは、適切なスペル、文法構造、および大文字小文字の区別について、辞書に対して簡単にチェックできます。それを超えるものはすべて、人が勝つ「おしっこ一致」です最も力を持っているか、または「眉を打つ」ことによって、私は個人的に、やらないことに苦労しています。
私がコメントするとき、私はいつも自分の将来の自分と話しながら三人称でコメントします。 5年後にこのコードに戻る場合、何を知る必要がありますか？何が役に立ち、何が混乱し、何がコードで古くなりますか？検索可能なパブリックAPIを生成するコードをドキュメント化することと、未知のサードパーティに価値を提供するコメントコードとの間には、たとえそのサードパーティが自分自身であっても、違いがあります。
これは良いリトマス試験です。あなたがプロジェクトの唯一のメンバーだった場合。あなたは自分がプロジェクトの唯一のメンバーになると知っていました。あなたのコーディング標準には何がありますか？将来は、コードを簡潔でわかりやすく、理解しやすくする必要があります。すべての行にコメントを付けなかった理由について、自分でコードレビューをしませんか？チェックインした100個のファイルに対して作成したすべてのコメントを確認しますか？そうでない場合、なぜ他の人を強制するのですか？
これらの議論で見逃されているのは、Future Youもこのプロジェクトの開発者であることです。価値について尋ねるとき、明日はあなたもコメントから価値を引き出すことができる人です。チームの規模は、私の意見では問題ではありません。チームの経験は問題ではなく、頻繁に変化します。
これをレビューするコメントコードの量はペースメーカーが患者をクラッシュさせて殺すことを止めません。コードに影響を与えるコメントについて話したら、今はコメントではなくコードについて話しています。誰かを殺すためのコメントが欠けているだけなら、その過程で何か他の臭いがする。
このタイプの厳密なコーディング方法に対するソリューションは、ソフトウェア自体を作成する方法としてすでに提供されています。そして、それはコメントとは何の関係もありません。コメントの問題は、製品が最終的に機能する方法に影響を与えないことです。世界の最高のコメントは、ペースメーカーに組み込まれたときにソフトウェアがクラッシュするのを防ぐことはできません。または、ポータブルEKGで電気信号を測定する場合。
2種類のコメントがあります。
機械読み取り可能なコメント
Javadoc、JSDoc、Doxygenなどのコメントスタイルは、一連のコードが提供するパブリックインターフェイスにコメントを付ける方法です。そのインターフェースは、他の1人の開発者（2人のチームの専有コード）、未知の数の開発者（JMSなど）、または部門全体でのみ使用できます。このコードは自動化されたプロセスで読み取ることができ、HTML、PDFなどのコメントを読み取る別の方法が生成されます。
このタイプのコメントは、標準を簡単に作成できます。これは、すべてのパブリックに呼び出し可能なメソッド、関数、クラスに必要なコメントが含まれるようにする客観的なプロセスになります。ヘッダー、パラメーター、説明などエル。これは、他のチームがコードを簡単に見つけて使用できるようにするためです。
私はクレイジーに見えることをしていますが、実際にはそうではありません
これらのコメントは、このコードが特定の方法で記述された理由を他のユーザーが確認できるようにするためにあります。おそらく、コードが実行されているプロセッサーに数値エラーがあり、常に切り捨てられますが、開発者は通常、切り上げられるコードを扱います。そのため、コードに触れた開発者が現在のコンテキストが通常何かをしている理由を理解できるようにコメントしますseem不合理ですが、実際にはそのように書かれていましたわざと。
このタイプのコードは、非常に多くの問題を引き起こします。通常、コメントは外され、後で新しい開発者によって発見され、「修正」されます。したがって、すべてを壊します。それでも、コメントは実際に何かが壊れることを防がない理由を説明するためだけにあります。
コメントは信頼できません
コメントは最終的に役に立たず、信頼できません。コメントは通常、プログラムの実行方法を変更しません。そしてもしそうなら、あなたのプロセスはより多くの問題を引き起こしています。コメントは後付けであり、決して他になり得ません。コンピュータで処理されるのはコードだけなので、コードは重要なことです。
これはひどく聞こえるかもしれませんが、我慢してください。これら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がこのような古いハードウェアとソフトウェアを使用している理由です。生死にかかわるときは、「ちょっとした変更を加えてチェックインする」だけではありません。
コメントは命を救うこととは何の関係もありません。コメントは人間のためのものであり、人間はコメントを書いても間違いを犯します。人間を信用しないでください。エルゴ、コメントを信用しないでください。コメントはあなたの解決策ではありません。
コメントについて話すとき、2つの異なることを暗示しています。それらは同じではなく、区別は重要です。
Documentationは、コードの一部である外向きのビット-そのインターフェースについて説明します。
通常、ツールを使用すると、それらを「スタンドアロン」で読み取ることができます。つまり、基礎となるコードを同時に見ていません。
すべてのインターフェースを文書化する必要があります（たとえば、プライベートメソッドを除く各メソッド）。入力、出力、その他の期待、制限など、特に制約やテストなどで表現できないものについて説明する必要があります（どれだけ詳細に、どこに行くかはプロジェクトによって異なります）。
優れたドキュメントにより、潜在的な消費者はコードを使用するかどうか、いつ、どのように使用するかを決定できます。
コメントソースコードの目的は異なります。それらはソースコードを見る人々のためにあります。彼らは主に実装について説明します。
コメントは、基になるコードの間で常に読み込まれます。
コメントは、意外な決定や複雑なアルゴリズム、または取られなかったオプション（および推論）を説明する必要があります。それらはそこにあるので、将来の開発者は前任者の思考プロセスを理解し、そうでなければ見落とすか、探すために多くの時間を費やすかもしれない情報を手元に持っています。
# 'map' outperforms 'for' here by a factor of 10
// This line works around an obscure bug in IE10, see issue #12053
-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.
コメントがないことから何も推測できません。もちろん、コメントは周囲のコードと同じくらい間違っているかもしれません。判断は、著者側と読者側の両方で行われなければなりません。
すべての行にコメントを付けることは、疑わしい付加価値のある作業であり、機会費用が伴います。すべての行をコメント化する必要があると言うルールがある場合、それは得られますが、重要な部分がコメント化されることを犠牲にしてwell。
しかし、それよりも悪いことです。すべての行がコメント化されている場合、コメントの目的は無効になります。コメントはノイズになり、コードを読みにくくします。明確にするのではなく、あいまいにします。さらに、無差別コメントは本当に重要なコメントを見つけるのを難しくします。
コメントもドキュメントも、それらが説明するコードの品質のいかなる種類の測定または保証も提供しません。正規のQAの代わりにはなりません。彼らの目的は、将来を見据えたものです。つまり、彼らとやり取りする人が間違いを犯さないように助けることを期待しています。
要約、コーディング標準は文書化を必要とする可能性があり、必要です（自動化されたチェックは、文書化されていない関数/メソッドを見つけるのに役立ちますが、人間は依然として文書が適切かどうかをチェックする必要があります）。コメントは判断の呼びかけであり、スタイルガイドはこれを認めるべきです。決してコメントしない人、何も考えずにコメントする人は挑戦することを期待するべきです。
重要なコメントを事前に知ることができないため、コメント基準を体系化することはできません。
ただし、これは非常に重要なコードなので、コードが正しくコメント化されていることを確認する必要があります。解決策は、コードレビューの標準を用意することです-理解しやすさに関するコードレビューのコメントを要求します。
これは、無意味なチェックリストにならないことを保証するものではありませんが、少なくともコードを読みにくくすることを防ぎます。そしてそれをより良くする可能性があります。
これには、コードレビュー自体が意味のないジェスチャーではない文化が必要です。コードを読みにくくなるように送り返すのは良いことであり、侮辱や煩わしさではありません。それと同じくらい重要で、それが不明確であると言っているものは、読者の失敗として見られません。
読めないコードは、ある程度、不可避です。なぜなら、ライターはコンテキストに没頭しており、x、y、またはzを知っている場合にのみ明らかである場合に、明白なものを目にします。
そのため、良いフィードバックを与えるというルールを設定することはできませんが、レビューをスポットチェックできます。プログラマーではないマネージャーでさえもそうすることができます-本当の質問はコードが読めるように書かれたのではなく、コード実際に読めるので、それはそれを読んだ人だけが決定できます。
コードのすべての行にコメントしますか？ いいえ。
あなたが話している他のルールの目的は、それを避けることです。
可読コードへのコメントはせいぜい冗長であり、最悪の場合、存在しないコメントの目的を探す読者を捨てます。
自明であるコード全体にコメントを付けると、追加情報を提供せずに読む量が2倍になります。そのような冗長性が報われるかどうかはわかりません。 42人が「display_error "コメントが"警告を表示します "と表示されていますが、コードの変更を想像してください。今すぐ修正できる場所が2つあります。このスタイルには、コピーと貼り付けのネガがあることがわかります。
私は、コードがドキュメンテーション以外のコメントを必要としないのが最適だと思います。
まったく逆のスタイルがありますが、ラインについて疑問がある場合は、次のいずれかです。
コードが複雑すぎるため、コードの一部に意味的な意味を持つ名前を付けて関数にリファクタリングする必要があります。複雑な
ifであっても、アルゴリズムの一部であっても構いません。 （または巧妙なLINQワンライナー）単純化できない場合、十分な言語の慣用句がわかりません。
（私は個人的には厳格なコメントなしルールの狂信者ではありませんが、最初から気をつけるべき良い考え方だと思います。）
このすべてを考えると、このアイデアを捉えた優れたコーディング標準を作成することさえ可能ですか？
プロセスも。私たちの基準はレビュアーにかなりの信用を与えました。それらが悪意のないものであると仮定すると、これはうまく機能します。
「変数oとは何ですか？」と尋ねられたら、名前を変更します。彼がこのブロックが何をするのか尋ねたら、リファクタリングするかコメントしてください。何かが明確であるかどうかの議論があった場合、レビュー担当者がそれを取得しなかった場合は、当然のことながらそうではありません。ごくまれに、ごく少数の友人からのセカンドオピニオンのようなものがありました。
平均して、チームの平均的なプログラマーが理解できるコードを入手する必要があります。 IMOは冗長な情報を避け、チームの他の少なくとも1人のメンバーがコードを理解できるようにします。
また、絶対はありませんでした。私たちは小さなグループでしたが。 5人のグループでコンセンサスを見つけるのは簡単です。
質問：
このすべてを考えると、このアイデアを捉えた優れたコーディング標準を作成することさえ可能ですか？ピアレビューに関連するものの、「42行目にコメントするのを忘れた」というメモを生成する、無頓着なチェックリストアクティビティにはならないもの。
コメントは、読者にその言語を教育するようなものであってはなりません。読者は作家よりも言語をよく理解していると想定する必要がありますが、作家よりもコンテキストははるかに少なくなります。
このコードの読者は、あなたの例から、exit()がアプリケーションを終了することを知っているはずです-したがって、コメントは冗長になります：
/* Exit the application */
exit();
冗長なコメントはDRYの違反です。コードへの変更およびは必ずしもコメントに反映されず、実際のコードが反映されていないコメントが残ります。やっている。
ただし、何かをしている理由を説明するコメントは、特にコード自体の意味を簡単に伝えることができない場合に役立ちます。
Pythonの PEP 8 （Pythonのスタイルガイド）には、インラインコメントに関する次のガイドラインがあります。
インラインコメントは慎重に使用してください。
インラインコメントは、ステートメントと同じ行にあるコメントです。インラインコメントは、ステートメントから少なくとも2つのスペースで区切る必要があります。 ＃と1つのスペースで始まる必要があります。
インラインコメントは不必要であり、明白に述べている場合は実際には注意散漫になります。これを行わないでください：
x = x + 1 # Increment xしかし、時々、これは便利です：
x = x + 1 # Compensate for border
そのような例を与えられて、私は個人的にさらに一歩前進することを好み、このコメントも排除しようとするでしょう。たとえば、私は次の場所に到着する可能性があります。
border_compensation = 1
compensated_x = x + border_compensation
コードの作成 自己文書化は新しいアイデアではありません 。
実際の質問に戻ります：
このすべてを考えると、このアイデアを捉えた優れたコーディング標準を作成することさえ可能ですか？
PEP 8のガイダンスと例は、このアイデアを捉えた優れたコーディング標準を示していると思います。はい、可能だと思います。
このようなコメントが表示されたとき、私が時々このように書いていると思います。それは、作成者がコメントに仕様を書き、各コメントを調べて実装しているためです。
実際の機能ではなく、必要な機能の点で理解できるコードを生成するコーディング標準を作成する必要がある場合（エラーを特定できるようにするため）、仕様の定義、文書化、およびリンク方法について実際に話し合っています。最終製品？
編集----
明確にするために。私はコメント対tdd対ユニットテストのどちらに入るのかは知りません。または、行ごとにコメントを提案することは良い/悪いことです
例で話されているコメントのスタイルを見るかもしれない理由を提案しているだけです。
そして、そのコメントから、コメントに関するコーディング標準が実際にある種の仕様ドキュメントの要件としてより適切に記述されるかどうかが問われます。
つまり、コメントはコードの目的を説明するためのものであり、仕様も仕様です
このすべてを考えると、このアイデアを捉えた優れたコーディング標準を作成することさえ可能ですか？ピアレビューに関連するものの、「42行目にコメントするのを忘れた」というメモを生成する、無頓着なチェックリストアクティビティにはならないもの。
これは明らかにドキュメンテーションを超えています-これはコードの構造、選択されたアルゴリズムなどに触れています。要件の分析と設計にさえ触れているかもしれません。
私の一番のルールは「明白なことを文書化しないこと」です。 ＃2のルールは「明白なコードを書く」です。
安全性が重要なコード（私が作業する必要がなかったので、神に感謝します）の場合、これは必要ですが、十分な最初のステップにはほど遠いです。避けなければならない言語機能を強制する必要がある場合もあります（「scanf( "%s", input );何らかの理由でを使用しないでください」という強制的な標準を複数見てきました。
私見それは両方を行う必要があります。すべての行にコメントするのはばかげています。
i++; /* Increment i */
iをインクリメントする理由がまったくわからない。これを少し拡張すると、典型的なDoxygenスタイルのコメントが得られます。これにより、コードの目的や機能のアイデアを提供せずに大量の言い回しが生成されます。 （少なくとも私が今まで見た限りでは、そのようなシステムを使用して有用なドキュメントを書くことは可能かもしれないことは認めますが、私は息を止めていません。）
OTOH、関数（または論理的なグループ化）の先頭に適切なコメントブロックを記述し、達成すべきことと、それが明白ではない場合にどのように役立つかを説明します。あなたが私なら、関連する方程式のLaTeXコードや、論文への参照などを含めることもできます。 「これは、ハミルトンジャコビ方程式を解くためのWENOスキームを実装します。
自己文書化コードのベストプラクティスは主流の合意ではありません-理解しやすいコードが暗号コードよりも優れていることは広く受け入れられていますが、複雑なコードを常にリファクタリングする必要があるかどうか、またはコメントしてもよいかどうかについて誰もが同意するわけではありませんそれ。
しかし、この議論はpiecesであるコードの難しいを理解することについてです-そしてあなたはコメントについて話しているeach and everyコードの行。理解するのが難しいコード行は非常にまれであるはずです-ほとんどの行がこのように複雑である場合、smart-assワンライナーを使いすぎているので、停止する必要があります！確かに、行の役割は時々理解するのが少し難しいかもしれませんが、それはより大きなコードのコンテキストにおける役割です-行自体が行うことはほとんど常に簡単です。
したがって、コメント行ではなく、コードの一部にコメントを付ける必要があります。特定のコメントが参照する行の近くに配置される場合がありますが、これらのコメントはまだ大きなコードを参照しています。それらはその行が何をするのか/なぜするのかを記述しません-それらはそのコードでそれが何をするのか、そして/またはそのコードでなぜそれが必要なのかを記述します。
したがって、コメント化する必要があるのは行ではなく、より大きなコードです。すべてのコードにコメントを付ける必要がありますか？いいえ、ハロルド・アベルソン氏は、「プログラムは、人が読むために、そして偶然にマシンが実行するためだけに書かなければならない」と述べました。しかし、コメントはonlyであり、人々は読むことができます-マシンはそれらを実行しません。コーディング標準がすべての行/コードに冗長なコメントを書くことを強制する場合、それらを書く必要がある開発者に負担をかけるだけではありません-あなたはreadをしなければならない開発者にも負担をかけます！
これは問題です。読んだコメントのほとんどが冗長である場合、コメントに注意を払うのをやめて（コメントは冗長なジャンクであることがわかっているため）、見逃してしまいます重要 =コメント。だから私は言う-重要なコメントだけを書くので、誰かがコードでコメントを見つけたとき、彼らはコードを理解するためにそれを読む価値があることを知るでしょう。
フローチャートを復活させる時が来ました！ （本当にではなく、ちょっと待ってください）
先日、古いフローチャートテンプレートを見つけました。私はそれを宿題とジョークにのみ使用しました（あなたは良い愚かなフローチャートを愛する必要があります）。しかし、この時点でさえ、まだフローチャートを使用していたほとんどの商用プログラマーは、コードからそれらを自動的に生成していました（これは、フローチャートの本来の目的を完全に損なうものでした。ただし、より高いレベルの言語では、フローチャートは松葉杖からホーブルに変更されました。なぜですか？フローチャートの抽象化はコードと同じでした。表示されたコメントは、コードと同じ抽象化レベルにあるという点でホーブルです。適切なコメントは、コードとは異なる抽象化レベルにあります。これを行う最も簡単な方法は、コードが何を処理するのかをコメントに使用することです。他の方法は、複雑な手順をより簡単な代替に分解するか、マネージャーレベルの抽象化することです。
私は述べられているように質問に答えます：
これを踏まえると、このアイデアを捉えた優れたコーディング標準を作成することさえ可能ですか？
はい。 WYSIWYG。適切なコーディング標準は、文字通り「次のコードが何をするかと理由」です。
言い換えると、私のコードレビューは、コードの読みやすさに関する文字通りのコメントであり、1-1は私の精神状態から生じます。
私は、読者として（まだ、最小限の標準として、経験は少ないが合理的な読者のメンタルモデル）、次のコードの目的や作業方法を理解していません
一般的に、「私は、あなたが馬鹿ではないと期待できる上級開発者として、最初はこのコードを理解していなかったか、なぜこのコードが存在するのか、またはそれが何であるのかを理解していなかった場合、「これはもっと読みやすくする必要があります」なので、説明する必要があります。」.
これは、「あなたが意味のない標準に従わなかった」という言説を「あなたのコードには特定の読みやすさの欠陥がある実際的な問題につながる」に変わります。
明示する必要がある2番目の標準は、「午前2時の緊急テスト」です。
このコードに慣れていないバックアップで、携帯電話を使用せずにチリアンデスで休暇中に午前2時の本番緊急ブリッジコール中にデバッグすると、コードのどのような問題があるのかわかりますか？
これは主観的に聞こえるかもしれませんが、実際には簡単に測定できます。本番環境の緊急時に夜間デバッグを行うと予想されるジュニアチームメンバーをランダムに呼び出し、特定のコメント化されていないコードがどのように機能するか、またその理由を説明してもらいます。そこ。
この回答 ほとんどの問題をカバーしましたが、重要なことが1つあります。
コードのすべての行、シーケンス、ステートメント、セクション、構造、関数、メソッド、クラス、パッケージ、コンポーネント、...のコメントを検討します。
たとえばdoxygenなど、コードからドキュメントを生成するツールがあります。そのようなツールを使用する場合は、ファイル、関数、クラスなどにコメントを付けるのが理にかなっています。関数の名前が自明であっても、ドキュメントを読んでいる人は感謝するでしょうので、一貫性を保つために引き続き使用しています。