通常表示 ]  [ 簡易表示 ]  [ シンプル表示 ]

「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典【シンプル表示】 ~ IT用語を日本語に ~

■第二十回:ソースコードにコメントを書くべきか


さてさてさて、久しぶりにコラムを投稿してみますよ。超不定期連載「分かりそう」で「分からない」でも「分かった」気になれるITコラムでございまぁす。このコーナーでは、各用語の説明ページでは取り上げにくいIT関連のネタをテーマに、だらだらと思いついたことを書いていきます。みなさんが「あぁ、なんか役に立ちそうな気もするけど、役に立たないかなぁ。でも、もしかしたら役に立つかも」と思える情報を発信できるように頑張ります!


はじめに


栄えある第二十回目のテーマは……ピヨピヨピヨピヨ(ぴよぴよ的ドラムロール)……じゃん!

ソースコードにコメントを書くべきか

です。

たまにはプログラマっぽいことを書いてみようと思ったのが、今回のコラムを書くに至ったきっかけです。

プログラマっぽい人はご存じだと思いますが、巷には「コメントは書いた方が良いよ」派と「コメントなんて書かなくて良いよ」派があります。

「コメントは書いた方が良いよ」派の主張は「書いた方が分かりやすいじゃん!」です。
「コメントなんて書かなくて良いよ」派の主張は「コメントを見ないと理解できないようなコードを書くな!」です。

ふむふむ。
どちらの意見も一定の理解は得られそうですね。

実際のところ、どっちが良いのでしょうか?
私なりの考えを書いていきます。

ちなみに、お忙しい人向けに先に結論を書いておくと

私は「コメントは書いた方が良いよ」派

です。
これから「えー、コメントなんて書かなくて良いじゃん」な意見に対して、ぶーぶー文句を書いていきます。
「コメントなんて書かなくて良いよ」派の人、ごめんなさい。


予備知識


そもそも「ソースコード」とか「コメント」とかの意味が分からない人は、このページを読まないと思いますが、一応、説明しておきますね。

まず、ソースコードは「人間語で書いたプログラムの元ネタ」です。


コラム20

ものすごい大雑把な説明ですが、人間語で書いたソースコードは「コンパイル」と呼ばれる作業をすることで、コンピュータさんが動かせるプログラムに変身します。


コラム20_2

次に、コメントは「ソースコードに書く人間様用のメモ書き」です。
人間様には見えるけどコンピュータさんには見えないインクを使って文字を書くイメージです。


コラム20_3

コメントは、プログラムの処理には影響しません。
人間同士の意思疎通のため、ソースコードを書いた人からソースコードを見る人に対して何かを伝える目的で書きます。

以上が予備知識です。
ソースコードとコメントについては、何となく理解できましたかね?


コメントは注釈だよ


それでは、本題に入ります。

ソースコードに書くコメントって必要ですかね?
それとも不要ですかね?

必要です。

コメント不要派の意見は、乱暴にまとめれば

コメントが必要になるコードを書くな

でしょう。

1.必要なことは、ソースコード内で表現するべし!
2.表現できないのであれば、そもそもの設計が悪い!


という論調が多いのではないでしょうか。

実は、私も、この意見には賛成です。
「コメントがないと理解できないようなコードを書くなよ~」とは思います。

ですが、だからといって「コメントが不要」とは言えません。

私のイメージでは、ソースコードは本(文章)です。
小説でもノンフィクションでも好きなものを想像してください。

ソースコードに書くコメントは、その文章内の用語に対する「注釈」です。
本文や本文内で登場する用語の「補足説明」の位置付けです。

確かに、注釈が多い本は読みやすくありません。
必要なことをすべて本文内で説明している方が、話に没頭できます。

ですが、だからといって「注釈なんて滅ぶべし!」との結論にはならないですよね。
特に専門書なんかでは、注釈がない方が不親切に感じます。


コメントが必要ないコードを本当に書けているの?


繰り返しになりますが、コメント不要派の意見は、乱暴にまとめれば

コメントが必要になるコードを書くな

でしょう。

これなんですけどね……。

この意見を見る度に思うのですよ。
「あなたは本当にコメントが必要ないコードを書けてるの?」って。

というかですよ。

そもそもの話として

コメントの必要ないコードなんて現実的に書けるの?

と思うのです。

そう考える根拠は

人によって技術レベルが違うから

です。

入社半年で新人研修が終わったばかりのド新人プログラマと、経験年数ウン十年のベテランエンジニアが同じ技術レベルなんてことは、あり得ませんよね?
仕事で書いたコードの場合、後の修正をド新人がする可能性もあれば、ベテランがする可能性もあります。

その点を考慮すると、少し複雑な処理を書く際に悩んでしまうのです。

私は(自分で作るのだから)コメントを書かなくても、分かる。
ある程度の経験を積んだエンジニアであれば、コードを見れば分かる……はず。
でも……この処理を隣の席に座っている新人君が見て理解できるかな……?

そんな風に考えると、もう駄目ですね。
「あー、後から質問されたら面倒くせーなー。ここに日本語で説明を書いておいてやるか」となってしまうのです。

皮肉でも当てつけでもなくて純粋な疑問なのですが、コメント不要派の人は、どの程度の技術レベルを想定して「コメントを書かなくても分かる」と判断しているのでしょうか?

「仕事なら、ある程度の技術レベルは担保されているはず」と判断するのでしょうか。
でも実際問題、技術者のレベルってビックリするくらいピンキリですよね。

この業界の事情を考えると、優秀な人が元気な状態でメンテを担当してくれると期待するのは楽観的すぎると思うのです。
ということで、どうしても私は、(仕事であれば)細かくコメントを書いてしまいます。


処理の直訳コメントは無駄?


さて、ここまでは大雑把に「コメント」全般に対して必要・不要を語ってみました。
次に、もう少し細かく分けて見てみます。

今回、取り上げるのは

必要なさそうなコメント

です。
特に

処理の直訳コメント

について語ってみます。

処理の直訳コメントというのは、例えば

//「hensu」が「piyota」だったら「piyo!」と表示する
if(hensu == "piyota"){
  print "piyo!";
}




//「hensu」が「piyota」だったら「piyo!」と表示する

のように「そんなん、コードを見れば分かるでしょ!」な内容のコメントです。

うん、これは書く必要ないですね。
不要なコメントです。

……が、私は結構、この手のコメントを(仕事では)書きます。
ごめんなさい。

理由は、上でも書きましたが「新人さんが見るかもしれないから」です。

上から目線で申し訳ないのですが、私は新人さんの技術レベルをかなり低く見積もっています。
実際のコードを眺めても、瞬間的に実際の処理に脳内変換できないでしょ、多分。
だから、コメントの日本語部分だけを読んでいっても処理の概要がつかめるようにしてあげたいのです。

ということで、私は処理の直訳コメントを書きます。

「必要か?」と問われれば、悩ましいところですけどね。

ある程度の経験を積んだ技術者にとっては不要でしょう。
経験の少ない人からすれば、ありがたいはずです。

ベテランと新人だったら新人の方がミスする可能性は高いでしょう。
だったら、新人に配慮した方が、全体のミスの数は減るはずです。
全体のミスが減れば、必然的に私の仕事量も減ります、多分。
だから新人の方に配慮してあげます。ベテランは自分で頑張れ!


まとめ


今回は「ソースコードにコメントを書くべきか」をテーマに、好き勝手に語ってみました。
ここまで語ってきたとおり

私は「コメントは書いた方が良いよ」派

です。

ただし、現実的には

すべては状況次第

だと考えています。

自分しか見ないコードやベテランで優秀な技術者が集っている現場であれば、(書かないという選択肢も含めた)必要最低限で良いと思います。
コメントをメンテするのも手間ですしね。

新人さんや経験の浅い人が見る可能性がある場合は、コメントを書いてあげるべきです。
そして何をどれだけ書くかの基準は「あなたが必要だと思うこと」ではなく「相手が必要だと思いそうなこと」です。

「処理の直訳コメントなんて無駄」と思う人もいるでしょう。
私も本音で言えば無駄だと思います。

ですが、それを必要とする人がいるのであれば書いてあげるべきです。
それが優秀で経験豊富なベテランからド新人な若手に対する贈り物じゃないですかね。


蛇足なおまけ


コメントの必要性を熱く語っておいてなんですが、私は自分しか見ないソースコードにはコメントを書きません。コード見れば分かるし。
本音で言えば、コメントを書くの面倒くさいです(-A-)



思いつきで始めて惰性で続けている「分かりそう」で「分からない」でも「分かった」気になれるITコラムですが、いかがでしたでしょうか。また何かネタがあったら、ちまちまと更新していきます。コンゴトモヨロシク。




■用語検索