ソースコード中のコメントした方がいいこと、悪いこと

著者:杉浦

ソースコード中のコメントした方がいいこと、悪いこと

 ソースコード中には自由にコメントを書くことができます。コメントの良い点はプログラミング言語の記法に縛られることなく自然言語で書き手の意図を読み手に知らせることが出来る点です。コメントの悪い点はソースコード中の文字数が増えるところです。
 良い点が悪い点を超える際にのみコメントを記述することが理想になります。しかしながら困ったことに読み手がどのような人かによって良い点が悪い点を超える瞬間は大きく左右されます。例えば、次のようなコードがあります。

array_object = Array.prototype.slice.call(array_like_object)//array_like_objectを配列に変換する

Array.prototype.slice.callはjavascriptで配列っぽいオブジェクトを配列として変換したい時によく使われる慣用句みたいなものです。”Array.prototype.slice.call”(完全一致)でググると約171,100件もヒットします。散々使われ倒しているため、javascriptをやり込んでいる少なくない人にとって、このコメントは余分な情報で邪魔者です。一方で、Array.prototype.slice.call(引数)という文面には引数を配列に変換するという意味の単語はまるで使われていません。これがarray_like_objectを配列に変換するコードだと連想することは難しいでしょう。初めて読んだ時は自分も何だこれとなりました。javascriptを学んでいる途中の人にはこのコメントは必要でありがたいものです。慣れという部分でコメントをするべきしないべきかが変わり境界は曖昧です。
 明確にコメントを行うべきでないという場合はソースコード中の記述がそのままコメントの内容と同じになるときです。javascriptのES6記法では配列っぽいオブジェクトを配列として変換したい時に次の様な記述ができます。

array_object = Array.from(array_like_object)//array_like_objectを配列に変換する

 コメントはいらないのではないかというくらい動作を連想しやすい記述です。そのまま英語として読めるくらいです。このような際にコメントは多くの人にとって邪魔なものになるでしょう。
 おまけに極端な場合を紹介します。
 情報を伝えないコメントは単に無駄なだけでするべきでないコメントです。コメントアウトされている過去のコードは特にこの手のコメントになりやすいです。
 コメント行がより多くのコード行を説明できる場合、コメントは有用になりやすいです。プログラム、ファイル、関数のようなまとまり全体を説明する場合、大体これにあてはまります。コメント十行でコード数百行を説明するような感じです。

  • この記事いいね! (0)

著者について

杉浦 administrator