どんなコードを書いたのか忘れた頃に役立つコメントの書き方

少し前にIRCやTwitterで @tagomoris さんらが、コードに対して執拗にコメントを書くことを推奨していたのを見かけた。



自分も気をつけなければと思い影響を受けたので、ブログに書いておく。

でも、多分、ほんとに当たり前のことしか書いてないんだと思う。

自分はコメントについて小一時間まとまった時間を使って考えたことは正直なかった。
もちろん何度も考えていますけど、「コメントとは、、ぬぬぬぬ」って何時間も考えたことはなかった。
無かったので、一時間くらいは考えても良いだろうと考えた。

コードからとれる意味とは何なのか


Tweetに出てくる「コードからとれる意味」は「何故そのように書いたのか」と「最終的に達成したい目標は何か」の2つの意味を指し示しており、これらがコードから感じられなくなるならコメントを書けと言ってると理解した。

そうですね。

執拗、とはどの程度の頻度なのか


「執拗さ」についてはIRCで複数のエンジニアが質問たり意見を出し合ったりして、以下の様なコメントの書き方が推奨されたと思う。

- 最低でもブロックごとに書く
-- ブロック : コードを読みやすくするための改行で区切った部分コード
--- 毎行書く位で調度良いという意見と、ブロック単位くらいが現実的だという意見があった

はい。

その他にもコメントを書く際の注意点ってあるよね


コメントを書く際の注意すべき点は、他にも沢山あるだろう。
世の中の優れたエンジニアはそれを知識として発信しているだろう。

ということで、ネット上を20分くらいクロールしてピンとくる意見を集めた。
英語圏のサイトだけから。

やるべきこと(やれ)

- そもそも意図が伝わるコードを書け
- 何故そう書いたのか、その方法を選んだ理由の説明を書け
- 用途が分かる説明的な変数名を使え
- 目的を説明するクラス名、メソッド名を使え
- 英語で書け。でも、英語が微妙なら日本語で書け
# 読者が日本人しかいないコメントなら日本語でいいだろう

- そのコード全体のメリットや狙いを序文を書け
- シンプルに少ない言葉で書け
- コードをメンテするときに書け、更新しろ
- 記憶での補完がいらないように書け
- 行コメントで書け
- 各メソッドにJavadoc形式のAPIドキュメントを書いとけ
# C++ではそうだよな。Perl向けにはDoxygen::Filterっていうのもあるのか

- 一部分のコードを切り取ったときに過不足が出ないようにコメントを書け
- コードはきちんとインデントしろ

やらないようにすべきこと(やるな)

- 何をしているコードなのか、処理の説明は書くな
- 書いた人の名前、日付、所属などを書くな
- 特定の読者を想定するな
- コメントを書きすぎるな
- 使ってないコメントにコードを書くな
- というか使ってないコードを消せ
- コードに追記・変更をした範囲外にコメントを書くな
- コードの中で宣誓するな
# 後でコメントを書く、ってコメントを書きがち。。

- コードでユーザの行動に制約をかけるな
# 入力チェックはコードでやれってこと

- 間違ったコメントを書くな

つまりこれらは、自分にとって、何を書いたのか忘れた頃に役立つコメントの書き方


そのコードが生まれた理由を説明するコメントは質も量も大切だということだ。

他にも注意することは色々あるだろうし、コードにコメントを書くべきではないと主張する人も見かけた。
けど、そういうのは、この記事のブックマークのコメント欄に書いてくれる人がいるんじゃないかと思う。

コメントは量より質、という言葉はよく見かけられる。
そして僕は無駄なコメントを書かないように気をつけるあまりコメントを書かなくなる。

でも実際には僕は周りの同僚と較べてグレートなコードを書くエンジニアでは無い。
なのでそもそも質とか言ってないで、やることをサボらないでやるしか無い。

無駄なコメントを書かないようになるためには、コードの質を高める必要があるが、実際にそれがいつでも完璧にできるかは分からない。

また、書いたコードが目的を達成できているのか、達成するうえで効率は良いのか、はそれを説明する文がついていなければ短時間に判断できない。

数カ月後に自分が今考えていることを全部思い出せるとは限らないし、自分の腕が吹き飛んだら僕はそれ以上コードをスムーズに書くことはできない。

効果的なコメントはあればある程良くて、とにかくコードと同じで書くしかないんだろう。

ということで少し前からコメントの書き方を少しずつ変えている。

参考資料


言語設計者たちが考えること

[Amazonで詳細を見る]

コメントはそのコードが存在する理由、その意図、その意図を達成する上で用いている小細工を説明するべきなのです。


リーダブルコード

[Amazonで詳細を見る]

コードを理解するのに役立つものなら何でもいいから書こう


- http://javarevisited.blogspot.jp/2011/08/code-comments-java-best-practices.html
- http://java.dzone.com/news/four-things-know-when-writing
- http://allthingsoracle.com/how-to-make-comments-the-most-important-code-you-write/
- http://www.devtopics.com/13-tips-to-comment-your-code/
- などなど


# 日本語で書かれた良い資料だと思った。


投稿者:としのり  日時:23:59:59 | コメント | トラックバック |
blog comments powered by Disqus