不必要なコメント・必要なコメント(2/2)

気付いたら前回の更新から3か月も経っていますが、今回は「必要なコメント」を題材に書いてみたいと思います。 忙しすぎてブログを書く心の余裕がなかったんですが、ようやく落ち着いたので。いつもいつも忙しいって言っている気がするなあ。

必要なコメント一覧

疑問点を残しておくコメント

他人のコードを途中から自分が引き継ぐことになったんですが、ところどころ制御の怪しいコードが見受けられたので疑問に思った内容をコメントで残しておきました。ちょうどその時、前の実装者が休み期間だったので...。後日その方が出社して僕のコメントを見て、間違っていたところは修正する，意図的だったところは解説コメントに書き換える，という更新がされていました。後で聞けばいいやだと忘れがちなので、自分の場合こういうケースはコードに直接書いてしまいます。どうせ開発終了時には消えるであろう一時的なコメントであれば躊躇う必要はないと思います。

あとで手を付けます系コメント

"tommy TODO" のように未実装であることを明示しておくもの。関数は用意したけど仕様未定のため関数の中は空っぽとかの時にこれを書いておきます。開発初期に多いので結局これも開発終了時には消えます。未実装部分が残ったままになっていないかの検索ワードにもなります。でもTODOはいろんな人が書いていたりするので、検索ワードとして被る可能性が大です。ある先輩は被らないように XXX と書いていたそうですが、なぜか他の実装者がそれを見習って XXX と書くようになり結局被った、という話もあります。笑

絵で示すコメント

百聞は一見に如かずに近いですが、言葉で説明されるより目で見た方が分かりやすい場合がプログラミングでもあります。音声信号処理をしていると回路の制御をプログラムすることが多いんですが、ちょっとした回路図をコメントで添えておくと途端に分かりやすくなったりします。当然大きな図になる場合は別ファイルに描きます。

リファクタリングしたいけどなあ...系コメント

汚いコードを見るとどうしてもリファクタリングしたくなって精神が乱れます。（僕だけ？）コードをいじるほどの時間の余裕はないから放置するけどこのままではいいと思ってないよと明示するために、本来はここをこう変えるべきというコメントを残しておくことがあります。他人のコードを引き継いだ時が大半。プライド高い人におすすめ。

理解に時間がかかった時の解説コメント

次の人がすんなり理解できるように。コードのアルゴリズムそのものが改善できる場合も多し。

まとめ

前回の「不必要なコメント」
不必要なコメント・必要なコメント(1/2) - ジャトミカ学習帳
で書いたことほど取り上げるものはないなあという印象。まあ要らないものがはっきりすれば要るものも分かりますからね。どちらかというと不必要なものを削ることの方が自分の中でプライオリティーは高いです。 でも今回の「絵で示すコメント」とか、普段なかなかやらないであろうコメントもいざやってみると新たな世界が開ける気分になります。