読者です 読者をやめる 読者になる 読者になる

コードを直訳したコメントは必要?

ちょっと気になったので読んでみた。


コードを直訳したコメントは必要なのか?「要る派」と「要らない派のまとめ」【 社畜ちゃん台詞メーカー 】 - Togetterまとめ


タイトルを見て不要としか思えずどんな意見が出てるかと思ったら、意外にも要る派が多いことにびっくり。
要る派の意見をいくつかピックアップしてみる。

  • わからない人が多い

非エンジニアとかを想定している人もいたが、そもそもそのようなプログラミングがわからない人向けに記述する必要はないだろう。
設計書とか仕様書とかで説明するべきだと思う。

  • 検索用

本当に直訳コメントを検索するか?
使われている箇所を調べたり、なにを表しているかなど検索する場合、元の関数や変数の名前で検索するよね。
コメントをあてにして検索するのは気休めになるくらいだと思う。

  • 英語がわからない・日本語だとすぐわかる

本当に英語が苦手という意味で言っている人がいるが、どうなんでしょう?
使う英単語なんて中学レベルくらいじゃないのかな。
あとは業務固有の単語とか。
それから、日本語だとすぐわかると言っているが、正確な仕様を確認するには関数であれば中身を見るしかないよね。

  • コメントがあっても困ることない

意外とそれなりの経験あるプログラマでもこのような意見があるように見えたが、直訳コメントを頼りにしてコードを追っていったり、理解しようとするのは危険だろう。
コメントはコメントであってプログラムの動作にはまったく影響しない。
プログラムを理解するにはコードを見るしかない。



自分のコメントの書き方としては、

処理のまとまりごとに見出しを入れる。
わかりずらいと思われる処理については、その意図やなにを求めているのかを書く。
あとは、必要に応じて関数、クラス、メソッド、変数コメントに説明を入れる。

という感じか。

すこし心配なのは、プログラマなのにコードを見ずにとりあえずわかったと自分を納得させるため、とか思っている人がいるような気がする。

私個人は、直訳コメント要らない派。