コメントを書くべきか?(中級者向け)

コーディングに慣れてきて、リーダブルに書けるようになってくると「あれ、コメントってひょっとして邪魔なだけじゃない?」という考えが首をもたげることがあります。

この考えはそのまま発展すると「完璧にコーディングするとコメントはなくなる」という思想に変化していきます。

あまり世間には顔を出しませんが、こういった思想の方は少なからずいるのではないかと思います。予想ですが。どれだけハイエンドの人でも書かない人いませんか?アレです。

そういう人に向けて「でもやっぱりコメントは必要だよ」と説得してみたいと思います。


完璧には書けない

マシン語は別ですが、プログラミング言語は言葉で表現します。

そして言葉というのは曖昧なものです。

曖昧なもので、しかも2,3単語で正しい意味を表現するのは不可能と言っていいです。


ソースコード上に書けないものがある

もちろん、極力意図に反しない使われ方をしないように設計するべきですが、それでも書けないものがあります。

特に複雑なもの、ビジネスロジック、いつどこで利用されるものか、どのように使用してほしいか(deprecatedとかも)


仕様は変化する

ある時には一意に決まったものが、後々一意に決まらなくなるケースがあります。

その修正時に全てを変更できればいいですが、それでは修正のたびに全ソースを確認する必要が出てしまいます。極力冗長にして、ヒントを残しておく方が後に改修する人に優しいです。


「ソースコードを読めば分かる」は危険

「どのように使用されているか」の関係を見ればわかるから、コメントは要らないと感じるかもしれません。

しかし関係だけでは意味を正しく切り取ることはできません。

例えば

Xは哺乳類である。

Xは言葉を話す。

Xは二足歩行する。

この時Xが人間だと推測するかもしれませんが、ひょっとしたら雇用者かもしれません。

さらに、ソースは変化します。一部の関係は追加・削除・変更されたりするかもしれません。


「コメントが間違ったまま放置されても動くから怖い」「メンテされないリスク」

どちらかというと、コメントはコードより仕様書に近いものです。

「仕様書が間違ったまま放置される」

「仕様書がメンテされない」

よりも

「仕様書がない」

ほうが怖くないですか?

また、コメントはバージョン管理上にあると思いますが、仕様書は大抵バージョン管理上にありません。不具合があった時、どちらのほうが原因を遡りやすいかは分かると思います。

それにコメントはおそらくPull Requestの時にレビューされると思います。そういう意味でもプログラマーにとってありがたい仕様書の一部なのではないでしょうか。

もちろんコメントを過信するのは危険で、書いてあるコードをチェックしなければならないのは当たり前だと思います。「コメントも完璧でなければならない」ではなく「ヒント」程度に考えるとどうでしょうか。


「コメントは自動テストできないから不安」

まず自動テストできたら安心というのが危ない気がしますが。

上記で書いたように、コメントは仕様書と考えてみましょう。

仕様書も自動テストはできません。現状、目視で確認するよりありません。

でも一般的な仕様書よりは、コードと一対一で対応しているので間違っているかの確認は取りやすいと思います。


次に触る人が完璧だとは限らない

「この程度のコード理解できて当たり前」はやめましょう。

誰だって慣れない時期はあるんです。


というか、OSSには大体コメント書いてますよ

有名なライブラリとかSDKとか、中を見たら大体コメントびっしり書いてますよ。

コメント不要論に行き着いたなら、彼らが間違ってるか、貴方が間違ってるかのどっちかです。


というか、リーダブルコードにもっとちゃんと書いてますよ

虎の威を借る

https://www.oreilly.co.jp/books/9784873115658/


コメントがないと考古学が始まる

コメントがない案件を引き継ぐと、その瞬間に考古学が始まります。プログラマーが何人居たか、誰がいつ編集したか、どういう意図で編集したか、誰に訊けるか、現状の仕様はどうか、仕様に変更はあったか。

ようやく一つの光が見えた頃には1日が終わっています。

「進捗どうですか?」「進捗ダメです」

死にたい・・・


コメントを書いてもしょうがない場所

でも全部にコメント書くのってムダっぽい感じしますよね。わかります。

特に「そのコメント書いても情報量増えてないし、分かりやすくもなってないし、冗長にも書けない!」と言える場所は不要かと思います。


どこにコメントを書くべきか

リーダブルコードを読んでください。詳しく書いています。

だと投げやりすぎるので、最低限欲しい場所を。


宣言(特に説明が必要そうなもの)

変数、クラス、その他の宣言。

ここに書かないとノーヒントになるので非常に厳しいです。


インターフェイス

そこにコメントが書かれていると「これをまず読めばいいんだな」とわかります。無駄なコードを読まなくていいです。


紛らわしい部分

言語だから曖昧な部分は出ます。


全体像、俯瞰的なこと

残念ながら現在の言語では、複数のモジュールを俯瞰的に表示することはできません。


意図、お気持ち、メッセージ

注意書き。難しいこと。伝えたいこと。優しさ。


まとめ

書いてよ(懇願)