この記事の目的
一般的なルールはあるものコメントは各職場や個人の考えによって書かれることが多い。
いろんな方の意見を聞いて何が正解かわからなくなった新人エンジニアが答えを探す
きっかけ
新しい職場でコメントについて先輩社員の方からご指摘をいただいたので
リーダブルコードを読み返してコメントの作法について考えてみました
これまでの私のコメントに関する体験
職場1：人が短期でどんどん入れ替わる職場
コメント記法も各々の自由。特にルールも無い状態
職場2：リーダーA
コメントは書くな、コードを読めば理解できるはずという感じの方針。
必要最小限のみコメントを書く。
リーダーB
コメントは多いほど良い、ぱっと見でわかることでもコメントで残そう。
必要以上にコメント書くようになる。
職場3：⇦いまココ
この機会にコメントに関して自身の経験を通して再確認させられたこと
コメントは端的に要約して短くまとめる、冗長にならない
必要な情報だけコメントで残す。
不必要な情報が混在すると必要な情報が分かりにくくなる。
コードの説明のためのコメントではなく機能の説明をする
そのコードでどんな機能を持たせたいのかをか書く。
コードを見ればわかることをいちいち書く必要はない
丁寧に説明しようとして何でもかんでもコメントするとかえって分かりにくくなる。
無駄なコメントを読んだらその分コードを読む時間が無くなる。
コード把握しやすくするためのコメントで分かりにくくなっては意味がない。
誰に書くのかをしっかりイメージする
- そのコードを見るチームのメンバー
- 1年後の自分
- コードを書いた自分自身が後からわかるように書く
そもそもコメントが必要ないコードを書く
- 命名の段階でわかりやすい名前を付ける
考えを残しておく
コードを書いた際に自分が何を考えて書いたのかを明確にしておく。
まとめ
本質は振り返ってみるととても基本的なことでした。
何事にも基本は大事だと再認識させられました。
良い習慣を身につけられるように今後も意識的にコメントを残してきたい。