コメントすべきでないこと、すべきなこと
コメントの目的とはなんでしょうか？
それは書き手の意図を読み手に知らせることです。
ただし、全ての意図をコメントすればいいわけではありません。
コメントを読むということはその分だけコードを読む時間が減るので、書くならばコードを読むより価値がある必要があります。
以下ではコメントすべきでないこと、すべきことを見ていきます。
コメントすべきでないこと
- コードからすぐにわかることを書かない
例えば以下のようなコメントが該当しそうです。
# 引数を二つ与えて、その合計を返す関数 def total(a, b) a + b end total(2, 5) #=> 7
- ひどい名前を補足するようなコメントを書かない
ひどい名前ならその名前を変えることをまず検討すべきです。
ひどいコードに優れたコメントをつけるより、優れたコードを目指しましょう💪
コメントすべきこと
- 自分の考え
優れたコメントというのは考えを記録するためのものと定義されています。
# a, b, cの3つの手段を試したが、bが最も計算量を抑えることができたので、この実装にしている
みたいなことでしょうか。
- コードの欠陥
コードの欠陥にはコメントを残しておきましょう。
後でプロジェクト内で探しやすいようにprefixをつけておくと便利です。
| 記法 | 意味 |
|---|---|
| TODO: | 後で手を付ける |
| FIXME: | 不具合がある |
| HACK: | 無理矢理解決している |
| WARN: | 問題あり |
| MEMO: | 実装メモ |
# TODO: クエリ減らす # HACK: N+1発生してる # WARN: セキュリティホールあり
- 定数
定数を定義する時には、おぼろげながらに浮かんでくることはありません。必ず何かしらの意味や背景があるはずです。
1クラス最大40人であれば以下のようになるでしょうか。
# 1クラスは最大40人 MAX_STUDENT = 40
- プロジェクトに途中から入る人に説明するようなこと
他の人にコードがどのように見えるか想像し、その人がどこで疑問を持ちそうか、どこで間違えそうかを考えて全体の要約コメントを残してあげるのが良さそうです。
ここでいう他の人とは、プロジェクトを熟知していない人のことです。
ライターズブロック
プログラマがコメントを書きたがらないのは、コメントをうまく書くのは大変だと思っているからだそう。
こうした「ライターズブロック（行き詰まってしまって文章が書けないこと）」を解消するための手順が紹介されていた。
（エントリーを書く時にも使えそう🤔）
- 頭の中にあるコメントをとにかく書き出す（例:とんでもない数のクエリが飛んどる）
- コメントを読んで改善が必要なものを見つける（とんでもない→すごい数の、飛んどる→発行されている）
- 改善する（すごい数のクエリが発行されている）
終わりに
上記のことを実践していくことで、適切なコメントによる優れたコード、他の人が読んだ時に理解まで最短であるコードを実現できそうですね💪
