解説スタイルは、読者がコードを理解する方法に影響しますか？

この質問は、過去2か月間私を悩ませてきました。

少し前に、優れたプログラマーである友人がいくつかのサンプルコードを教えてくれました。初めて、独自のコメント整理スタイルに気づきました。彼は私がコード自体をより快適にするような方法でコメントを設計するためにいくつかの努力をしました。例えば：

/////////////////////////////////////////////                                                   //                                             //
//  This code prints a basic "Hello world" //
// message to the console screen. You can  //
// change the text in the brackets.        //
//                                         //
/////////////////////////////////////////////

#include <iostream>

int main() {
  cout << "Hello world";

}

彼が単に書くことができたとき

/* This code prints a basic "Hello world" message to the console, change text in brackets */

 #include <iostream>

int main() {
  cout << "Hello world";

}

この種の例は、より大きなスケールでのみです。私はこれを専門的な状況では少し非生産的だと思いますが、学習状況では、それは理想的なようです。

ここでの問題は、コメントのスタイルが読者がコードを理解する方法に影響を与えるかどうかです。私の個人的な意見では、オプション＃1は見た目がきれいで、＃2より簡単にフォローできます。コードについてコメントする方法は、コードを理解する能力に影響しますか、それとも単に時間とスペースを無駄にしていますか？

はい

空白とコメントの観点から見たプログラムのレイアウトは、開発者がコードを読みやすくする上で大きな影響を与えます。

Prettier to the eye and more easy to follow 主観的であり、すべてのプログラマにとって同じではありません。

そうは言っても、画面上により多くのコードを一度に表示することを好む開発者もいれば、より多くの空白/コメントを好む開発者もいます。

一日の終わりに、あなたはあなたが読むことに慣れているコードをより快適に読むでしょう。

Clean Codeの作者であるボブ・マーティンおじさんは、コメントは悪いコードを言い訳するために頻繁に使用され、可能な限り避けられるべきであると主張しています。代わりに、コード自体は、他の開発者が簡単に拾い上げて作業を開始できるように、十分に読みやすく整理されている必要があります。

コードの書式設定は読みやすさに大きな違いをもたらす可能性があると思いますが、ほとんどの場合、適切に書式設定された（または単にインデントされているだけの）コードは、ライターが単に切り取りを行うのではなく、実際に少し注意を払ったという温かくあいまいな感じを与えます手持ちのスニペットを貼り付けます。

コメントについてはよくわかりません。私が書いたコードは、コメントが役立つと固く信じています。一方、仕事で出くわす「エンタープライズ」コードを理解したい場合は、コメントをすべて削除し、コードを再フォーマットしてインデントを統一し、紙に印刷して詳細に読み、基本的なブロックにマークを付けます。鉛筆などで

この矛盾（私：良いコメント;みんな：誤解を招くコメント）は、コメントが非常に過大評価されていると私に思わせます。自分でも。

はい、コメントのスタイルは読みやすさに影響します（どうすればそれができないのでしょうか？）。過度のフォーマットはそれだけです：過度です。

良いコメントを書くことは、コードを書くのと同じように、練習して洗練するスキルです。

私見、最初のものは、クラスが何をするか、またはソースファイルの最初にコメントするのに適しています。2つ目は、次のコードブロックの機能を説明するのに適しています。メソッドについては、私は使用します

//////////////////////////////////////////////////////////////////////
This code prints a basic "Hello world" message to the console screen. You can change the text in the brackets. 

他の素晴らしい答えに加えて、注釈スタイルの一貫性は別のポイントだと思います。同じ種類のタスクに異なる種類のコメントスタイルを使用すると、コードの可読性がかなり損なわれます。

あなたが与える例は少し極端ですが、はい、コメントには非常に重要な機能があります。

コードの作成者は、何をする必要があるかについてのメンタルモデルを持っています。コメントは

• そのメンタルモデルとは何かを読者に伝える
• メンタルモデルとコードがそれを実装する方法の間のマッピングを表現します。

このようにして、要件が変更された場合、元の作成者または後で来た人がコードに対応する変更を正しく行うことができる可能性が高くなります。

それ自体を説明するような方法でコードを書いてみるのも良いことですが、それが100％成功することはめったにないので、コメントが必要です。

質問に対する簡単な答えは「はい」です。コメントとコメントスタイルは、コードの読みやすさと理解しやすさに明らかに影響します。それは一般的な考え方ですが、コメントの説明とそのデザインの品質は純粋に主観的なものです。

他人のコードやコメントを読んでみたことはありますか？ほとんどのプログラマーは、独自のスタイルと知識レベルに基づいてコードとコメントを記述します。彼らのコメントとコードを読むことは、彼らの心に入り込み、彼らの実践を追おうとするようなものです。

この問題を回避する1つの方法は、コード構造、目的、およびコメントの基本的なガイドラインを簡潔に説明する基本的な「原則/スタイルガイド」を使用することです。このガイドには、コードを書く人々と、コードを読んで拡張する可能性のある残りすべてが一貫して従う必要があります。

文体的には、2つの形式のコメントを使用します（C ++ / Javaの場合）。

/**
 * Multi-line comment
 */

または

// Single-line comment

構文の強調表示を備えたIDEでコメントに注意を引くことができます。書式設定に精通する必要はありません。

はい、コメントのスタイルは確かに読みやすさに影響します。コメントをすばやく識別してコメントを読まないようにできるコメントスタイルは、実際にコードの読み取りを行うときに非常に役立ちます。

IDEを使用してコメントを完全に最小化できるようにするコードコメントスタイルがさらに優れているため、コメントを読むためにエネルギーを費やす必要がありません。