きれいなコードのコメントとクラスのドキュメント

コメントに関して、新しい同僚と議論をしています。私たちはどちらもClean Codeが好きで、インラインコードのコメントを避け、クラスとメソッドの名前を使用してそれらの動作を表現する必要があるという事実にまったく問題ありません。

ただし、主に単一の責任原則パターンを維持しやすいように、クラスの目的と実際に何が表されているのかを説明しようとする小さなクラスの要約を追加するのが大好きです。また、メソッドが何をすべきかを説明する1行の要約をメソッドに追加することにも慣れています。典型的な例は簡単な方法です

public Product GetById(int productId) {...}

私は次のメソッドの概要を追加しています

/// <summary>
/// Retrieves a product by its id, returns null if no product was found.
/// </summary

メソッドがnullを返すという事実は文書化されるべきだと思います。メソッドを呼び出したい開発者は、メソッドがnullを返すか例外をスローするかどうかを確認するためにコードを開く必要はありません。インターフェースの一部であることがあるため、開発者はどのコードが実行されているのかさえ知りませんか？

しかし、私の同僚は、これらの種類のコメントは「コード臭」であり、「コメントは常に失敗」であると考えています（Robert C. Martin）。

コメントを追加せずに、これらの種類の知識を表現および伝達する方法はありますか？私はロバートC.マーティンの大ファンなので、少し混乱しています。要約はコメントと同じであるため、常に失敗しますか？

これはインラインコメントについての質問ではありません。

他の人が言ったように、APIドキュメントのコメントとインラインコメントには違いがあります。私の観点からの主な違いは、インラインコメントはコードと一緒に読み取られるのに対して、ドキュメンテーションコメントはコメントするものの署名と一緒に読み取られることです。

これにより、同じDRY原則を適用できます。コメントは署名と同じことを言っていますか？あなたの例を見てみましょう：

IDで製品を取得します

この部分は、名前GetByIdと戻り値の型からすでに見たものを繰り返しProductます。また、「取得する」と「取得する」の違いは何か、その区別についてのベアリングコードとコメントの違いについても疑問が生じます。だから、それは不必要で少し混乱します。どちらかといえば、コメントの実際の有用な第2部の邪魔になります。

製品が見つからなかった場合はnullを返します。

あ！これは署名だけでは確実に知ることができないものであり、有用な情報を提供します。

これをさらに一歩進めてください。人々は、コメントについて話すときのコードは匂いとして、問題はないコードかどうか、それがあるようにはコメントが必要ですが、コメントはコメントで情報を表現するために、コードをよりよく書くことができることを示しているかどうか。それが「コードのにおい」の意味です-「これをしないでください！」という意味ではなく、「これをしているのであれば、問題がある兆候かもしれない」という意味です。

したがって、同僚からこのnullに関するコメントがコードのにおいであると言われた場合、単純に彼らに質問する必要があります。彼らが実行可能な答えを持っている場合、あなたは何かを学びました。そうでなければ、おそらく彼らの苦情を殺してしまうでしょう。

この特定のケースに関しては、一般にヌルの問題は難しい問題であることがよく知られています。コードベースにガード句が散らばっている理由、ヌルチェックがコード契約の一般的な前提条件である理由、ヌルの存在が「10億ドルの間違い」と呼ばれている理由があります。実行可能なオプションはそれほど多くありません。しかし、C＃で見られる人気のあるものの1つは次のTry...規則です。

public bool TryGetById(int productId, out Product product);

他の言語では、型（Optionalまたはのような名前の場合が多い）を使用して、Maybe存在する場合と存在しない場合がある結果を示すのが慣用的な場合があります。

public Optional<Product> GetById(int productId);

ある意味で、この反コメントのスタンスはどこかで私たちを引き付けました。少なくとも、このコメントが匂いを表しているのか、どのような代替案が存在するのかを考えました。

元の署名よりも実際にこれらを好むかどうかは、まったく別の議論ですが、製品が見つからなかったときに何が起こるかをコメントするのではなく、少なくともコードで表現するオプションがあります。これらの選択肢のうち、どちらが良いと思うのか、同僚と話し合う必要があります。また、コメントについての包括的な独断的な発言を超えて先へ進むことを願っています。

ロバートC.マーティンの引用は文脈から外れています。ここにもう少しコンテキストのある引用を示します。

適切に配置されたコメントほど役立つものはありません。軽薄な独断的なコメントほどモジュールを混乱させることはできません。嘘や誤った情報を広める古い無愛想なコメントほど損傷を与えるものはない。

コメントは、シンドラーのリストとは異なります。それらは「純粋な」ものではありません。実際、コメントはせいぜい必要な悪です。プログラミング言語が十分に表現力がある場合、またはそれらの言語を微妙に使用して意図を表現する才能があれば、コメントはあまり必要ありません-おそらくまったくありません。

コメントを適切に使用することは、コードで自己表現できないことを補うためです。失敗という言葉を使用したことに注意してください。本気で言っているんだ。コメントは常に失敗です。私たちは常に彼らなしで自分自身を表現する方法を理解することはできませんが、それらの使用はお祝いの原因ではないため、それらを持っている必要があります。

したがって、コメントを書く必要がある立場にいるときは、考え直して、表を変えてコードで表現する方法がないかどうかを確認してください。コードで自分を表現するたびに、背中をなでてください。コメントを書くたびに、あなたは顔をしかめ、表現能力の障害を感じる必要があります。

（ここからコピーされますが、元の引用はClean Code：A Handbook of Agile Software Craftsmanshipからのものです）

この引用が「コメントは常に失敗」にどのように縮小されるかは、一部の人々が賢明な引用を文脈から外して愚かな教義に変える方法の良い例です。

APIドキュメント（javadocなど）はAPIをドキュメント化することになっているため、ユーザーはソースコードを読む必要なく APIを使用できます。そのため、この場合、ドキュメントでメソッドの機能を説明する必要があります。メソッド名で既に示されているため、「IDで製品を取得する」は冗長であると主張できますが、null返される可能性のある情報は明らかに重要ではありません。

コメントの必要性を避けたい場合はnull、APIをより明示的にすることで、根本的な問題（有効な戻り値としての使用）を削除する必要があります。たとえば、何らかの種類のOption<Product>型を返すことができるため、型シグネチャ自体は、製品が見つからない場合に返される内容を明確に伝えます。

しかし、いずれにしても、メソッド名と型シグネチャだけでAPIを完全に文書化することは現実的ではありません。ユーザーが知っておくべき追加の非自明な情報については、doc-commentsを使用してください。DateTime.AddMonths()BCLのAPIドキュメントをご覧ください。

AddMonthsメソッドは、うるう年と月の日数を考慮して、結果の月と年を計算し、結果のDateTimeオブジェクトの日の部分を調整します。結果の日が結果の月の有効な日でない場合、結果の月の最後の有効な日が使用されます。たとえば、3月31日+ 1か月= 4月30日。結果のDateTimeオブジェクトの時刻部分は、このインスタンスと同じままです。

メソッド名と署名だけを使用してこれを表現する方法はありません！もちろん、クラスのドキュメントにはこのレベルの詳細は必要ないかもしれませんが、これは単なる例です。

インラインコメントも悪くありません。

悪いコメントは悪いです。コードから自明に見えるものだけを説明するコメントの例、古典的な例は：

// increment x by one
x++;

変数またはメソッドの名前を変更するか、コードを再構築することで明らかにできる何かを説明するコメントは、コードのにおいです：

// data1 is the collection of tasks which failed during execution
var data1 = getData1();

これらはマーティンが反対するコメントの一種です。このコメントは、明確なコードの記述に失敗したことを示しています。この場合、変数とメソッドにわかりやすい名前を使用しています。コメント自体はもちろん問題ではありません。問題はコードを理解するためにコメントが必要なことです。

しかし、コメントがなければならないコードから明らかでないものはすべて、例えばを説明するために使用される理由コードは、特定の非自明な方法を書かれています：

// need to reset foo before calling bar due to a bug in the foo component.
foo.reset()
foo.bar();

過度に複雑なコードが行うことを説明するコメントも臭いですが、修正はコメントを禁止することではなく、修正はコードの修正です！実際の言い方では、複雑なコードは発生しますが（リファクタリングまで一時的にのみ）、通常の開発者が初めて完全なクリーンコードを記述することはありません。複雑なコードは、ないよりも、何を説明するコメントの書き込みをはるかに優れているような場合ではないコメントを書きます。このコメントにより、後でリファクタリングするのも簡単になります。

コードがやむを得ず複雑になる場合があります。複雑なアルゴリズムの場合もあれば、パフォーマンス上の理由から明快さを犠牲にするコードの場合もあります。再びコメントが必要です。

コードにコメントを付けることと、コードを文書化することには違いがあります。

• 後でコードを保守する、つまりコード自体を変更するには、コメントが必要です。

  実際、コメントは問題があると認識される場合があります。極端なポイントは、彼らがいると言うことであろう、常に十分な表現力もすることができませんでし言語（あなたのコード（理解するにはあまりにも難しいコード）内または言語内のいずれか、問題を示している。例えば、メソッドが返すことはありませんという事実はnull表すことができC＃のコードコントラクトを使用しますが、たとえばPHPのコードを使用してそれを表現する方法はありません）。

• 開発したオブジェクト（クラス、インターフェイス）を使用するには、ドキュメントが必要です。対象読者は異なります。ここで話しているのは、コードを維持して変更する人ではなく、ほとんど使用する必要のない人です。

  コードが何千行も読まなくてもクラスとインターフェースを使用できるようにするためにドキュメントが特別に用意されているため、コードが十分に明確であるためドキュメントを削除するのは正気です。

さて、同僚は本を読んで、彼らが言うことを取り入れ、考えずに、文脈を考慮せずに彼が学んだことを適用するようです。

関数が何をするかについてのコメントは、実装コードを捨てることができるようなものでなければなりません。関数のコメントを読んで、何の問題もなく実装の置換を書くことができます。

コメントで例外がスローされたかどうか、またはnilが返されたかどうかがわからない場合、それはできません。コメントは教えてくれない場合はさらに、あなたの例外がスローされるかどうかnilが返されるかどうかは、関数を呼び出すどこでも、そして、あなたはあなたのコードは、例外がスローされるかnilが返されるかどうか、正しく動作することを確認しなければなりません。

あなたの同僚はまったく間違っています。そして先に進み、すべての本を読んでください、しかしあなた自身のために考えてください。

PS。私はあなたのラインを見た「時々それはインターフェースの一部であるので、あなたは実行中のコードさえ知らない。」仮想関数だけでさえ、あなたは実行中のコードを知らない。さらに悪いことに、抽象クラスを作成した場合、コードすらありません！したがって、抽象関数を持つ抽象クラスがある場合、抽象関数に追加するコメントは、具象クラスの実装者がそれらをガイドしなければならない唯一のものです。これらのコメントは、たとえば、抽象クラスと具体的な実装を返すファクトリがあるだけで、実装のソースコードがまったく表示されない場合など、クラスのユーザーをガイドできる唯一のコメントでもあります。（そしてもちろん、1つの実装のソースコードを見るべきではありません）。

考慮すべきコメントには2つのタイプがあります-コードを知っている人に見えるコメントと、ドキュメントの生成に使用するコメントです。

ボブおじさんが言及しているコメントの種類は、コードを知っている人だけに見える種類です。彼が提唱しているのはDRYの形です。ソースコードを見ている人にとって、ソースコードは彼らが必要とするドキュメントでなければなりません。人々がソースコードにアクセスできる場合でも、コメントは必ずしも悪いものではありません。アルゴリズムが複雑な場合や、バグを修正したり新しい機能を追加しようとした場合に他の人がコードを壊さないように、なぜ自明でないアプローチを取っているのかを把握する必要があります。

説明しているコメントはAPIドキュメントです。これらは、実装を使用している人には見えますが、ソースコードにアクセスできない場合があります。ソースコードにアクセスできる場合でも、他のモジュールで作業している可能性があり、ソースコードを見ていません。これらの人々は、コードを書いているときに、このドキュメントをIDEで利用できると便利でしょう。

コメントの価値は、それが与える情報の価値から、それを読むおよび/または無視するのに必要な労力を引いたもので測定されます。したがって、コメントを分析すると

/// <summary>
/// Retrieves a product by its id, returns null if no product was found.
/// </summary>

価値とコストについては、次の3つのことがわかります。

1. Retrieves a product by its id関数の名前が言っていることを繰り返すので、価値のないコストです。削除する必要があります。

2. returns null if no product was found非常に貴重な情報です。他のコーダーが関数の実装を見なければならない時間を減らす可能性があります。私はそれが導入する読書コストよりも多くの読書を節約することをかなり確信しています。残るはずです。

3. 台詞

   /// <summary>
   /// </summary>
   

   情報を一切持ちません。コメントの読者には純粋なコストです。ドキュメントジェネレーターで必要な場合は正当化できますが、その場合は別のドキュメントジェネレーターを検討する必要があります。

   これが、ドキュメントジェネレーターの使用が議論の余地のあるアイデアである理由です。一般に、洗練されたドキュメントのためだけに、情報を含まない、または明白な内容を繰り返す多くの追加コメントが必要です。

私が他の答えのいずれにも見当たらないという観察：

コードを理解/使用するのに必要のないコメントでさえ、非常に価値があります。以下にそのような例を示します。

//XXX: The obvious way to do this would have been ...
//     However, since we need this functionality primarily for ...
//     doing this the non-obvious way of ...
//     gives us the advantage of ...

おそらく大量のテキスト、コードを理解/使用する必要はまったくありません。ただし、コードがそのように見える理由を説明します。それはコードを見る人を短くし、なぜそれが明白な方法で行われなかったのか疑問に思い、最初にこのようにコードが書かれた理由を理解するまでコードのリファクタリングを開始します。また、読者がリファクタリングに直接ジャンプしないほど賢い場合でも、コードがそのままの状態を維持する必要があることを理解する前に、コードがそのように見える理由を理解する必要があります。このコメントにより、文字通り何時間もの作業を節約できます。したがって、値はコストよりも高くなります。

同様に、コメントは、単に機能する方法ではなく、コードの意図を伝えることができます。そして、彼らは通常、コード自体の細部で失われている大きな絵を描くことができます。そのため、クラスのコメントに賛成するのは正しいことです。クラスの意図、他のクラスとどのように相互作用するか、どのように使用されるかなどを説明している場合、クラスコメントを最も重視します。

コメントされていないコードは悪いコードです。コードは、たとえば英語とほぼ同じ方法で読むことができるというのは（普遍的でないとしても）広く知られている神話です。解釈する必要があり、時間と労力を要する最も些細なコードを除きます。さらに、誰もが特定の言語の読み取りと書き込みの両方で異なるレベルの能力を持っています。著者と読者のコーディングスタイルおよび機能の違いは、正確な解釈を妨げる大きな障壁です。また、コードの実装から作成者の意図を引き出すことができるという神話でもあります。私の経験では、コメントを追加することはめったに間違っていません。

ロバート・マーティン他 コードが変更され、コメントが変更されていない可能性があるため、「悪臭」と見なしてください。私はそれが良いことだと言います（ユーザーに漏れを警告するために「悪臭」が家庭用ガスに追加されるのとまったく同じ方法で）。コメントを読むことは、実際のコードを解釈するための有用な出発点となります。それらが一致する場合、コードの信頼性が高まります。それらが異なる場合、警告臭が検出されたので、さらに調査する必要があります。「悪臭」の治療法は、臭いを取り除くことではなく、漏れを封じることです。

一部の言語（たとえば、F＃）では、このコメント/ドキュメント全体を実際にメソッドシグネチャで表現できます。これは、F＃では、特に許可されない限り、nullは一般に許可された値ではないためです。

F＃（および他のいくつかの関数型言語）で一般的なのは、nullの代わりにまたはのOption<T>いずれかのオプションタイプを使用することです。言語はこれを理解し、使用しようとすると両方のケースで一致するように強制します（そうでない場合は警告します）。NoneSome(T)

たとえば、F＃では、次のような署名を使用できます。

val GetProductById: int -> Option<Product>

そして、これは、1つのパラメーター（int）を受け取り、製品を返すか、値Noneを返す関数になります。

そして、あなたはこのようにそれを使用することができます

let product = GetProduct 42
match product with
| None -> printfn "No product found!"
| Some p -> DoThingWithProduct p

また、考えられる両方のケースに一致しない場合は、コンパイラの警告が表示されます。したがって、そこにnull参照例外を取得する方法はありません（もちろん、コンパイラの警告を無視しない限り）。関数のシグネチャを見れば、必要なものはすべてわかります。

もちろん、これにはあなたの言語がこのように設計されていることが必要です-C＃、Java、C ++などの多くの一般的な言語はそうではありません。したがって、これは現在の状況では役に立たないかもしれません。しかし、コメントなどに頼らずに静的に型付けされた方法でこの種の情報を表現できる言語が存在することを（できれば）嬉しいです:)

ここにはいくつかの素晴らしい答えがありますが、私は彼らが言うことを繰り返したくありません。ただし、コメントをいくつか追加します。（しゃれはありません。）

賢い人が作る声明はたくさんあります-ソフトウェア開発や他の多くの主題については、文脈で理解すると非常に良いアドバイスですが、文脈から外れたり、不適切な状況に適用したり、とんでもない極端。

コードは自己文書化されるべきであるという考えは、そのような素晴らしいアイデアの1つです。しかし、実際には、このアイデアの実用性には限界があります。

一つの落とし穴は、言語が明確かつ簡潔に文書化する必要があるものを文書化する機能を提供しない可能性があることです。コンピューター言語が改善されると、これはますます問題になります。しかし、私はそれが完全になくなったとは思わない。アセンブラーで書いた当時、「合計価格=非課税アイテムの価格+課税アイテムの価格+課税アイテムの価格*税率」などのコメントを含めることは非常に意味がありました。ある時点でレジスターにあったものは、必ずしも明白ではありませんでした。簡単な操作を行うには多くの手順が必要でした。しかし、もしあなたが現代の言語で書いているなら、そのようなコメントはコードの1行を言い換えるだけです。

「x = x + 7; // 7をxに追加」などのコメントを見ると、いつもイライラします。プラス記号が何を意味するのかを忘れていたら、すごい、ありがとう。私が本当に混乱するのは、「x」が何であるか、この特定の時間に7を追加する必要がある理由を知ることです。このコードは、「x」により意味のある名前を付け、7の代わりにシンボリック定数を使用することにより、自己文書化することができます。 。

追加のコメントが冗長になるように、関数名は関数が何をするかを正確に伝える必要があると言うのは素晴らしいことです。アイテム番号がデータベースのItemテーブルにあるかどうかをチェックし、trueまたはfalseを返し、「ValidateItemNumber」と呼ぶ関数を作成したときの思い出があります。まともな名前のように思えた。その後、他の誰かがやって来て、その関数を変更して、アイテムの注文を作成し、データベースを更新しましたが、名前は変更しませんでした。今、その名前は非常に誤解を招くものでした。本当にそれがはるかに多くのことをしたとき、それは1つの小さなことをしたように聞こえました。後に誰かがアイテム番号の検証に関する部分を取り出して別の場所でそれを行いましたが、それでも名前は変更しませんでした。そのため、関数はアイテム番号の検証とは関係ありませんでしたが、

しかし実際には、関数の名前は、その関数を構成するコードである限り、関数の名前がなければその関数が何をするかを完全に記述することはしばしば不可能です。名前は、すべてのパラメーターで実行される検証を正確に示していますか？例外条件はどうなりますか？すべての可能なあいまいさを綴りますか？ある時点で、名前は非常に長くなり、混乱を招きます。文字列BuildFullName（String firstname、String lastname）を適切な関数シグネチャとして受け入れます。名前が「最初、最後」、「最後、最初」、またはその他のバリエーションで表現されているかどうかはわかりませんが、名前の一方または両方の部分が空白の場合、結合された長さに制限を課す場合、それを超えた場合の動作、