続・コメント

自身が以前、ある開発者組織の研修を経験したときに、おもしろい経験をしたので参考までに紹介したいと思う。
それはコメントに関する指針についてのレクチャだった。まず、例題としてごく簡単なクラスをひとつだけ実装して、その内容に応じたコメントを記述したもらった。
対象はヘッダからはじまって、コンストラクタ、フィールド、パブリックアクセサ、パブリックメソッド、プライベートメソッド、プロクテッドメソッド、そして デストラクタ。
奇妙なことに判を押したようにそれらのコメント群の記述、粒度、文言は一致していた。そのときの生徒数はおよそ15名。この程度の人数だと思うかもしれないが、この統制のとれたコメントのノーテーションには、非常にびっくりした記憶がある。驚いたというのは、とても優秀な成績だったということではなく、この奇妙な統制についてだ。
ある意味、これだけの人数のチームで、これだけの統一感があるというのは、とても望ましいことだと思う。しかし、自身が思ったのはまったく違った。
実際的なコメントを読むと、自身の水準に照らし合わせれば、悪くはないが合格点はあげられない出来だった。

何が問題なのか？

一般的にコメントは適度な粒度が必要だ。シンプルに、かつ、必要にして充分な情報を提供できなくてはならない。もちろんこれは本質ではあるが、一朝一夕で記述できるほど甘くはない。
まず、考えなくてはならないのは、文脈に即した情報を網羅できているのか？ つまり、構造のコンテキストに応じた言葉の選択や論理で貫かれているだろうか？ というのが第1のポイント。
2つ目に、よく考えてほしいのは、果たしてこのコメントを読んで3週間後の自分は理解できるだろうか？ 半年後の自分は理解できるだろうか？ そして未だ見ぬ未来の実装者は、ここから必要な情報を得られるだろうか？
読めばわかる、という考え方は実は閉ざされた地平でしか通用しないある種の文明なのだ。共通基盤と一定水準の知識があってはじめて成立する、いわば方言、地方言語でしかない。
コメントはローカルであってはならない。参考までに、プロプライエタリ系の言語世界では、よくローカルな方言に陥りがちだ。もちろん、これは経験的に感じた傾向ではある。

翻ってオープンソースの世界はまた違った側面を持っている。誰に強制されるわけでもなく、コメント文化は成熟しているのが常だ。もちろんすべてのソースコードがそういうわけではないが、傾向としてグローバルな文化が根付ているように見える。これは、コメントという小さな視点だけではなく、実装やプロジェクトの運営方針に対して極めて規範的な空気感が常に流れているからではないだろうか？ と思うことが多い。
自らを律する。この地平で初めて他人のための仕事も成熟を遂げるのではないかと考えている。