ソースコードコメント

コメントとは

ソースコードは、人がコンピュータに動作を指示するためのものです。
ただしコメントは、人と人の会話です。
コメントで

• コードに注釈や解説を追加すること
• コードの論理や意図をより理解しやすくすること
• バグ修正履歴を記したりする

コメント利点

• 自分自身が何を書いたかをより理解することできる
• メンテナンスやアップグレードが容易
• 他のメンバーがコード理解しやすくなる
• エラーの特定やデバッグが迅速に行えるようになる

ではコメントが当たり前じゃないですか？と思ってる人多いと思いますが。
実際はコメントしない人、コメントする必要ない人も結構います。
次のはこの話を細かく見てみましょう。

コメント反対派

コメントを書かない理由が次のようなものがあります：

• コードを読んで理解できない場合、書き直すべき
• コードが変更、コメント更新されず　→誤解を招く説明
• シンプルで、よく書かれたコードのコメントは、既に明らかなコード自体を複製
• コメントを書くことはあなたを遅くし、あなたが集中すべき主なこと、つまりコード自体

優れたコードは自己文書化するべきです。コードを読んで理解できない場合、そのコードは良くないので、書き直すべきです。変数やメソッドの名前の良好な選択、直接的なアルゴリズムなどがこのカテゴリに該当します。
コメントに依存するコードは、それらをクラッチとして使用しています。つまり、コード自体が複雑または構造が悪いため、書き直す必要があります。
コードが時間とともに変更されると、コメントはしばしば更新されず、同期が取れなくなります。古いコメントは、最初のコメントが書かれた時と比べて、コードが現在何をするのかを誤ったまたは誤解を招く説明を提供します。
シンプルで、よく書かれたコードのコメントは、既に明らかなコード自体を複製します。一例としては、シンプルなgetterメソッドがあります。「フィールドXを取得する」コメントは、この状況では冗長です。
コメントの品質は、プログラマーによって大きく異なり、ユニットテスト、コミット前のフック、自動化されたコード品質分析などの実行可能コードと同じ厳格さには受けていません
コメントを書くことはあなたを遅くし、あなたが集中すべき主なこと、つまりコード自体から焦点をそらします。

コメント賛成派

コメントを書く理由以下のようなものがあります：

• 一般的にコードよりも読みやすく、早い
• ビジネスルール、プロセスを文書化
• ドキュメントに変換
• チームは、コードが複雑であっても、 コメントでコードを直接的に説明
• コメントを書くことは、思考の落とし穴と仮定を明らかにする
  2度考え一度はコード、コメント

コメントはコードの意図を明らかにします。 コードが明確でない場合、コメントはその目的をはるかに人間が読みやすい方法で明らかにします。

コメントはビジネスルールを文書化します。たとえば、コードが答えが42であると述べているかもしれませんが、なぜ答えが42であるのかをはっきりさせることはほとんどありません。
ビジネスはおそらく何らかのビジネス理論に基づいてこの決定を下しました。
そのため、それは持続的で、見つけやすく、誰もが不注意にルールを破るのを防ぐ場所で文書化するべきです。コメントはこの目的によく適しています。

コメントはプロセスを文書化します。前述のポイントと同様に、コードがプロセスまたは手順のシーケンスに従っている場合、各ステップとその依存関係をより人間に優しいフォーマットで説明するのは簡単です。

Javadoc、JSDocなどの生成。メソッド、フィールド、クラスに配置されたコメントは、
Web上で読むことも、IDEからアクセスすることもできるHTMLドキュメントに変換できます。
よく文書化されたコードは、ソースコードの中をのぞき見ることなく（これは容易にセーターの端から糸をほどくようなものになります！）、
自信を持って使用できるブラックボックスになります。
これはAPIに特に便利であり、よく文書化されていてフォローしやすいAPIやライブラリを使用したことがあり、他のものはそれほどではなく、
掘り下げて探し、探し回ることが必要で、いらいらしながら多くの時間を費やすことが必要です。

コメントは一般的にコードよりも読みやすく、早い。
チームは、コードが複雑であっても、よく書かれたコメントを頼りにして、コードを直接的に説明できます（先の可読性に関する議論は素晴らしい例です）。
コメントを書くのが遅いという反対面は、大抵の場合、それらは付随するコードを読むよりもはるかに早く読むことができます。

逆の立場になって初めてわかること
私はソースコードコメント書く派なんですが、反対派の意見から「コメントはいつでも必要なんですか」、「どんなコメントがいいですか」いろいろ考えました。

Good comment ≠ Good code

プログラマは最終的に良いソースコード書く必要なんです。コメントとソースを比べるとソースの方が大事と思います。
コメントでソース理解でよければ良いソースではなく、良いソースコードを書いて、コメントが必要なだけ追加したらいいです。
例：

上記のコードは、コメントでソースの流れ、何するのかを明確しました。それは良いコメントですよね。（コメントないと何してるのかちょっと理解しにくい）
では、これは良いソースコードですか？というと、答えはいいえ
簡単な列なので、たぶんすぐわかると思いますが。このソースの問題は変数名が無意味です。
以下のように変数名編集したら、確かに、ソース自体がめっちゃわかりやすい感じました。
そして、上記のコメントも必要なくなります。すばらしいいいい

結論

• ソースコメントはプログラミングにおいて良い習慣、やってほしい
• いいコメント書くより、とりあえず、良いソースコード書いてください
• ...

「どんなコメントが良いのか」「どんなコメントが悪いのか」などコメントについて話がまだまだいっぱいあるですが、
次回話しましょう。((´∀｀))