コードとコメントの黄金比はどれくらいですか?[閉まっている]

https://stackoverflow.com/questions/111563

02-07-2019
|

質問

コードの健全性が良好 (不良) であることを示すコードとコメントの比率はありますか?

適切にコーディングされていると考えられるオープンソースプロジェクトの例と、それぞれのコメント率を挙げていただけますか?

(すべてのプロジェクトに「真実」な比率はなく、この理論上の黄金比を示すつまらないプロジェクトが存在する可能性が非常に高いことは承知しています。まだ...）

解決

コメントは非常にまれで価値があり、ほとんどの場合「理由」を表現し、「方法」を表現することは決してありません (方法が複雑でコードから簡単に識別できない場合は例外です)。

すべてのコメントは、コードの意図をより明確にするためにリファクタリングが必要になる可能性があることを示すヒントです。どのコメントも、書いた瞬間に古くなってしまう危険性があります。

XML コメント以外にはほとんどコメントがありません。 xUnit.net プロジェクト, 、しかし一部の人々コードが明確で読みやすいと思われるようです。:)

他のヒント

他のプログラマーからのコードを修正しなければならない人はこう言います。 できるだけ多くのコメントを. 。古いコードの大きな問題は次のとおりです。「コードが何をするかわかりますね。これが問題であることがわかります。しかし、プログラマーがなぜこのように書いたのかはわかりません。」

バグを理解するには、次のことを知っておく必要があります。

何 すべき コードはそうしません（そうではありません）何コードはそうなります）とその理由。
すべての機能のコントラクト。たとえば、NullPointerException がある場合、バグはどこにあるのでしょうか?関数内でしょうか、それとも呼び出し関数内でしょうか?
すべての Hack では、問題を再現する方法 (言語バージョン、OS、OS バージョン) が説明されます。たとえば、サポートされなくなった古い Java VM に対するハックが多数あります。しかし、再現方法がわからないため、削除できるかどうかはわかりません。

割合としては2～3％と少なすぎます。大規模なプロジェクトや長期にわたるプロジェクトには 10% が適切だと思います。

申し訳ありませんが、経験則はありません。プログラマーは顧客となり、メソッドを呼び出す必要があるたびにコードを読む時間がないため、フレームワークやライブラリでは、インスタンスごとにさらに多くのコメントが必要になります。

コードを書いたり読んだりするプロジェクトでは、必要なコメントが少なくなるため、コメントとコードの比率ではなく、コードの読みやすさを向上させるように努めるべきです。

敬具

コメントはコードを説明するだけではなく、何かを実行するコード部分を探しているデバッガーをガイドします。

顧客の注文履歴を取得したり、敵プレイヤーが表示されているかどうかを計算したりするには、数十行のコードが必要になる場合があり、専門のプログラマーであっても、その動作を確認するのに数分かかる場合があります。「顧客の注文履歴を取得する」というコメントにより、注文履歴が問題ではないことがわかっている場合、デバッガはそのコードをまったく調査しなくなります。

あいまいな点、または説明する必要があると思う点はすべてコメントします。多くの場合、私はコメントしすぎます。なぜ？なぜなら、誰があなたのコードに取り組むか分からないからです。私は、チームの半分を、行で Enter キーを押すとバナナが得られることだけを理解しているサルに置き換える状況を想像してみたいと思います。したがって、彼らが少なくとも読み方を学べば、最初にコメントを読まなくても私の論理を変えることはないだろう。

事例とポイント:

// Delete the helloworld file
exec("rm -f helloworld.txt")

次のように変更されません:

exec("rm -rf /")

ありそうもないことはわかっていますが、場合によっては良い開発者はロジックを変更することが知られています。 それは正しくないようです バグや要件の変更があったからではありません。

コメント 0 は一般的にサブ文書化されたコードとみなされることに誰もが同意すると思います。最も自己文書化されたコードであっても、文書化できるのは内容だけであることに注意してください。 そこには;意図的に省略されたもの、最適化されたもの、試行されて破棄されたものなどは決してありません。基本的に、ソースファイルには常に英語が必要になります。そうしないと、重要な注意事項や設計上の決定が省略されることになります。

私は、皆さんが提唱している健全な原則 (これまでのところ、私は完全に同意しています) がコード統計にどのように変換されるかに興味があります。特に、どのオープンソースプロジェクトが十分に (過剰ではなく) 文書化されていると考えられているのか、またそのプロジェクトのコメント率はどのくらいなのかを調べます。

私には非常に単純な経験則があります。コードの一部 (関数や複雑なループなど) をコーディングするときに、15 秒以上立ち止まって考える必要がある場合、そのコードにはコメントが必要です。

それは私にとって本当にうまくいきます。次回、あなた、またはあなたと同じレベルでコードベース全体を理解している人がそのコード部分に遭遇したとき、すぐにわかるでしょう。なぜそれはそのように行われましたか。

LOC / LOcomment = yearsofexp / 5

私のルールは次のとおりです。言う必要があることとコードがある場合 できる ないそれを表現させられた場合は、コメントを書くことができます。それ以外の場合、コードが できる アイデアを表現するには、そのアイデアをコードまたはそのテストで表現する必要があります。

このルールに従う場合、コードでコメントが必要になるのは、ハードウェアまたはオペレーティングシステムの明らかでない問題に対処する場合、または最も明白なアルゴリズムが最適な選択ではない場合のみです。これらは「これは奇妙です」というコメントであり、実際には単なる対処メカニズムです。ほとんどの場合、コード内のコメントは実際には、よりわかりやすい方法で記述しなかったことに対する単なる謝罪であり、そのようなコメントは取り除いて削除する必要があります。

良いコメントであっても時間の経過とともに嘘になることはよくあるので、コメントのような実行やテストが不可能な場所にある情報は疑いの目で見るべきです。繰り返しになりますが、答えはまずコメントを削除してから削除することです。

私の理想の比率はゼロです。ただし、世界は理想的とは言えません。そのため、重要なアイデアを伝える他に方法がない場合は、コメントを受け付けます。

必要と思われる箇所にはコメントがあるはずです。それ以上でもそれ以下でもない。

6 週間以上の中断後にコードを再度見たときに、理解できないと思われる部分にコメントを付けてください。

コメントは最小限に留めるようにしています。コードは自己説明的であるべきであり、ソースコードは変更される傾向がありますが、ほとんどの場合、コメントは間違った説明として残ります。

黄金のコード/コメント比率は、

コーディング中に念頭に置いていたことを思い出させるために必要なコメント
コーディング中に念頭に置いていたことを他の人に思い出させるために必要なコメント
顧客が喜んでお金を払うコメント (良いコメントには時間がかかるため)
開発者が仕事の安全を理由に難読化されたコードを作成することに興味を持っている (開発者が難読化を回避できる会社で働いている場合)

これは、その比率がプロジェクトごと、チームごとに異なる理由も示しています。

黄金比なんてありません。コメントの数は、コード固有の複雑さに大きく依存します。CRUD アプリケーションを作成するだけの場合は、おそらく多くのコメントは必要ありません。オペレーティングシステムや RDBMS を作成している場合は、より複雑なコーディングを行うことになるため、おそらくコメントをさらに多くする必要があり、実行していることの理由をもう少し明確にする必要があります。

さまざまな言語のコメント率に関する実際のデータが必要な場合は、以下をご覧ください。ああ、ああ.

例として、次のようになります。さまざまな指標 Linux カーネルソースの場合。

誰も数字を教えてくれないと思いますが、ヘッダーファイルではソースよりもはるかに高いはずです。

クラスのヘッダーファイルには、そのヘッダーファイルを含めることでパブリックにアクセスできるすべてのクラス/関数/などが文書化されることが期待されます。プロトタイプが 1 行である関数を文書化するには、かなりの行数になる可能性があります (いいえ、関数とそのパラメーターに適切な名前を選択するだけでは十分ではありません。十分である可能性はありますが、そうでないこともよくあります)。コードの各行に対して 3 行のコメントが必要になることはありません。

実際のコードでは、これはさらに低くなります。コメントゼロを目指すべきだと考える過激派には私は同意しませんが、確かにコメントが必要だと思うなら、まずコードをより明確にできないかどうかを検討すべきです。

かなり異なる場合があります。たとえば、コードが非常にうまく書かれているため、コメントするのは時間の無駄になる場合があります。

数か月後にコードを確認し、コメントを読み、中断したところから簡単に再開できるように、十分なコメントが必要です。コードのライフストーリーが必要ない場合は、書かないでください。

コメントとコードの比率が適切であるということはありません。昔は、すべての関数の先頭に、その機能を説明するコメントが必要だと信じていた人もいました。

しかし、現代言語の出現により、コードはほとんど自己文書化されています。これは、コードにコメントを追加する唯一の理由は、奇妙な決定がどこから来たのかを説明するか、非常に複雑な主題の理解を助けるかのいずれかであることを意味します。

「黄金比」なんてものはありません。それは言語と書き方によって異なります。コードの表現力が高まるほど、自己文書化が可能になり、必要なコメントが少なくなります。それが流暢なインターフェイスの利点の 1 つです。

コードとコメントの固定比率を強制することはできません。そうしないと、次のようなノイズだらけのコードが完成します。

// Add one to i
i++;

これはコードを曇らせるだけです。

代わりに、コードの複雑さに注目して、何を説明する必要があるかを確認してください。おかしなロジック、特定のマジックナンバーが使用される理由、受信形式に関してどのような前提が存在するかなど。

メンテナの考え方にスイッチを入れて、今書いたコードに関して何を説明してもらいたいかを考えてください。

HTH。

乾杯、

ロブ

私の意見では、コメントには 3 つの用途があります。

説明するなぜコードはそれが行うことを実行します
モジュールのインターフェースを文書化する
ロジックの塊に対して他のアプローチが採用されなかった理由を説明する

コードが十分に基本的なことを実行している場合、なぜが明確である場合、ほとんどのドメインでほとんどの場合、ロジック内のコメントは最小限になるはずです...どれにも近づきません。コメントでは決して説明してはいけません何 (たとえば、この関数が Bar Publication で説明されている Foo アルゴリズムの実装であるなどの例外はあります)。説明が必要な場合は何あなたはやっている、やり方が悪い。

Steve McConnells () の書籍「Code Complete」には、コードコメントについての優れた議論があります (私は初版を持っていますが、現在は第 2 版だと思います) リンクテキスト)

要約すると、他の回答が述べたことを補強します-まれであるべきであり、その理由を説明してください-コメントを置き換えるために変数とメソッド名をリファクタリングできる場合は、それが優先されるべきです-ほとんどのIDEは何らかの種類のインテリセンスを提供しています（または私のように） Don Box がそれを「中毒性のためインテリクラック」と表現しているのを聞いたことがあります) より長い明確なバージョンの方がその意図をより明確に伝えることができるのに、変数/メソッド名を切り捨てる理由はありません。

0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero

「コメントなし」のコメントが付いた暗黙の「Do What I Mean」コマンドですか？

そのような比率はありません。

通常、コメントは、何かが本当に不明瞭である可能性がある状況でのみ存在する必要があります。

// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;

一方、コードを誰かに販売する場合は、できるだけ多くのコメントが必要になります。コメントのない 3D エンジンまたはその他のゲームミドルウェアを販売するイメージ。確かに、API ドキュメントなど。もこのようなミドルウェアの大きな部分を占めていますが、優れたコメント付きコードも同様に効果をもたらします。「Add 1 to i」のようなものは依然としてスパム的ですが、「CreateDevice() は最初に DirectX 10 が利用可能かどうかを確認し、利用できない場合は DirectX 9 デバイスにフォールバックします」のようなものは、たとえそれが些細なことであっても、非常に役立ちます。コードから見てください。

一般に、内部コードは販売するコードに比べてコメントがかなり少なくなりますが、例外が適用される場合があります。

私はコメントを使用してコードに注釈を付けることを好み、読みやすく、有益な変数が含まれていることを確認します。そうは言っても、私は、可能であればコメントと同じくらい有益になるように、コードの各行を記述するように努めたいと考えています。コメントを読む前に、そのコードが何をするのかについてしっかりと要点を把握できる必要があります。そうしないと、コードの実行が間違っています。

3% から 9.5% の間、多かれ少なかれ

コード 1 行あたり 2 つのコメントについての答えを探してここに来たと言わざるを得ません。たとえそれが誇張であっても、それは正しい方向です！代わりに、コメントをトリュフやその他の珍しい商品のように扱うことを推奨している人を見かけます。学術界特有の視点から見ると、コードの品質が低く、バージョン管理の使用がトリュフよりもさらにまれである場合、コメントが 100% 必要かどうかの自分自身の判断に反してでも、できるだけ多くのコメントを書くことをお勧めします。

コメントを書くことで作業が楽になります。なぜなら、これを書いているときに私は一体何を考えていたのかと考えてしまう可能性があるからです。

ライセンス： CC-BY-SA と帰属

所属していません StackOverflow