プログラミングを生業としていると、嫌でも他人のプログラムを読み解かなければならない場面は出てきます。
そのとき「いや、こんなコメントかかれても」と、いうコメントにたくさん出会う。
ここでは、アンチパターンとしての無意味なコメントを集めてみます。
//ここで変数に詰めます
ただただ無意味にプログラムが行っていることをなぞらえているコメント
うん、プログラム見ればそれは分かるよ。
それがプログラムを見ても分からないようなら、
よっぽどひどい記述の仕方か。
よっぽどひどい命名規約のどちらかだね。
処理の説明をしているコメントは多いです。
処理の説明ではなく、何故この処理が必要かを書いてもらえると有用なんですけどね。
同じような物に、
- //インスタンス化します。
- //～メソッドを呼びます。
- //ここでリターンします。
//この呼び出し関数では…
処理の流れを円滑につかむため関数の役割を解説であれば問題ないが、関数で行っている処理まで事細かに記述しているコメント
それは、関数側に記述されていれば良いし、そこまで説明しないと何をしているか分からない関数であるとするならば、それは関数の名前の付け方に問題があるか、関数の役割が多すぎる。
リファクタリングで関数を分解した際の置き土産の場合もあるので、察した場合はさくっとコメントを消してあげましょう。
または、インテリセンスの充実しているIDEを使用の際は関数側のコメントを厚くして、インテリセンスで確認できるようにしておきましょう。
//条件分岐の条件
If/Switch/Case文などで、条件だけをコメントで書いているケース
知りたいのは条件ではなくて
- 何故、条件分岐をしているのか
- この条件はどういった意味を持つのか
//20XX-XX-XX:修正履歴
修正履歴がソースに埋め込まれているケース。
最初は良いがソースが年齢を重ねるにつれてソースを閉める量が多くなって行きます。
そのうち、ソース 1:9 修正履歴コメントの様にソースを占める量を圧迫し、可読性が落ちます。
今の時代、ソース管理ツールを使わない開発って考えられないので、その役割はソース管理ツールに一任してはどうだろう。
//もう使わないロジック
ソースの特定ブロックが丸ごとコメント化されているケース
分からないではないが、これもソース管理ツールを使えば差分も見れるし、ソース管理に一任して欲しい。
ただ、短期スパンで修正リリースを繰り返し復活の可能性があり、一時的に残している場合もあるのでやむを得ない場合もある。（これすらも基本的にはソース管理でなんとかなるのだがリリースが優先される場合もある）
/* こんな場合にしていること*/
自分でも忘れてしまいそうなことがあるので、コメントに
//20XX-XX-XX以降、残っていたら不要なので削除
と言うコメントを入れて、次回観たときに消しています。
最後に
でもちょっとだけ…（これが良いこととは思っていないのですが）
そんな今まで紹介した無意味に思えるコメントにも実は意味があることもあるんです。
みんなのプログラミング人生を思い返してください。
最初から、クラスとインスタンスの関係を分かっていましたか？
でも、そんな違いの分からないメンバーでも実戦に投入しないと成長しないのです。
そんなとき、先輩プログラマーは後輩のサンプルとして使えるように、丁寧に丁寧にコメントを書きます。
//ここで、変数を定義して //ここでインスタンス化してください。 //ここでそのインスタンス化されたオブジェクトをつかって、こうしてください。
コメントは次にこのプログラムを見る人の道しるべです。
このコメントを読み後輩は同じように真似をしてその意味を覚えていくのです。
そして後輩達はそんなコメントも合わせてコピーし次のプログラムを作ります。
確認しつつ。
本来こういったことは、教育した上で開発に参画すべきであることは分かりますが、実際に投入される現場ではありえます。（是正すべきですが）
最初から豪腕プログラマーにはなれません、ちょっとだけイライラしないで微笑ましく見守る余裕を持ってあげてください。
そんな背景が分かって必要ないと判断できたら、きれいさっぱりそんなコメントは削除するなりリファクタリングしてあげましょう。
また、新人プログラマーが参画するその日まで。
コメント