コメンティングのすゝめ

コメンティングとは？

プログラムコードへ付けるコメント。
このコメントを付ける作業のことを「コメンティング」と定義します。

それって、コーディングでは？

一般的には、プログラムを作る作業のことを

• プログラミング
• コーディング
• 実装

と呼びます。
この作業にはプログラムコードを補足する説明、
いわゆるコメントを付けることも含んでいます。

含まれる・・・
私はこの「含まれる」という事が気に食わなかったのです。
コーディングとコメントを付ける作業を明確に分けたい！

コメントを付ける作業のことを、

「コメンティング」

と呼ぶことにしました。

分けていないと何がダメなの？

一言で言うと、
「コメント作業をナメるな！」
「魂込めてコメントを付けろ！」
ってことです。なぜか二言になってしまいました。

コメントはソフトウェアの実動作には一切関係ないが…

コメントが一切なくても実動作には問題ありません。
よって、コメントを付ける作業は後回しになりがちです。
その一方で、コメントの重要性は言わずもがなで色々な所で説かれています。
説かれているけれど、実際には以下のようなことがよく起きます。

• このコードの意図はなんだろう
• 保守を引き継いだがどうやって修正したら良いか分からん
• 難しい処理を実装しているこの関数（ライブラリなど）を流用するべきか判断に困る
• 自分で作ったのになぜこのコードのなっているのか思い出せない
• まじ納期間に合わねぇ！コメントは適当だぜ！いえーい。

などなど

そもそもコメントは何のため？

後で、プログラムコードを何がしかの理由で見る読むことになった人（自分も含む）が、
このプログラムコードは一体どうなってんの？と理解する際に、
理解を助けてくれるのが、コメントです。

実際に美しいコメント見たことある？

実際には、良いコメントだと感じるプログラムコードに出会うことは少ない。
何故なのか？

• 時間が足りなくなる
• プログラムコード自体が洗練されていないのでコメントも分かりにくくなる
• 実動作とは関係ないので手を抜いてしまう

このような理由が考えられます。

そこでコメンティング

この機能の実装には３日掛かるな。というタスクがあったとします。
この場合、コーディング２日、コメンティング１日
と行った見積もりを行います。
１日とにかくコメントを付け続ける作業を計画しておく。

朝会とかの報告で、
「コーディングが終わったので、今日はコメンティングします」
みたいな感じ。

理想：
　部下：実装が終わりました。
　上司：コメンティングは終わっているの？
　部下：コメントは付けてありますが、ひとまず実装は終わった感じです。
　上司：じゃぁ今日は１日コメンティングして。

洗練されたコメントを付けるために

コメントのコツを意識して１日（半日でも良いけど）かけてコメンティングすると、
いろいろな気づきがあるはずです。

• バグを見つける
• バグとは言えないけれど設計上の上手くないところを見つける
• さらに綺麗でエレガントな実装方法を見つける

見つけたら、実コードにもフィードバックしてあげましょう。
コメントも実コードも質がどんどん上がります。

コメントのコツ

コードの翻訳は避ける

見たら分かるコードを日本語に直訳するコメントは避ける。

*.c

// ユーザの情報を取得する
getUserInfo( userID );

意図していることをまず書こう

このプログラムコードの意図を書こう！

関数／メソッド／クラスの単位で概要を書こう

よく巷ではヘッダコメントと言われるやつです。

Andをつけない

シンプルさを保つために、「○○と△△」のようにAnd表現になるコメントを避けよう。
避けられない場合は、その処理や関数が複雑かどうかを再検討しよう。

シンプルさを重視せよ

流用したくなるような理路整然としたシンプルで本質が書いてあるコメントを目指せ！

意図していない「引数、使い方、動作環境」などを書く

意図していることはしっかり書いてあるが、
意図していないことをハッキリと書いてあるコメントは少ない。
意図していることと意図していないことが曖昧の場合は設計が足りない。

テストシナリオと期待値を書いておく

「こういう状態のとき、こういう動作を行えば、こうなることが期待される」
という形式で記述しておく。
参考：Gherkin（テストのための記法の1つ）

将来の自分へのラブレター

今わかっていても、暫くすると忘れる。
将来の自分へのラブレターと思って、
丁寧にコメントを付けよう！
方針や考えていたことをきちんとコメント化するのを忘れないように。

コメント化が難しい場合

コメントが難しい場合、例えばシンプルに語れない場合は、
おそらく何かが間違っている。
設計が難しかったり、コードが難しくなっている可能性があるので、
シンプルな設計やコードにならないか再検討した方が良い。

失敗したプログラム設計（実装方法）を書いておく

すでに試してみたが上手くいかなかった手法があれば書いておく。

参考にした文献のURLや書籍名を記録しておく

ネット記事を参考にすることが多いと思うが、元ネタ書いておくと理解の助けになる。
サンプルが書かれた程度の参考記事なのか、
公式ドキュメントからの引用ソースなのか、
はたまた公式ドキュメントの記述をこう解釈した。という結果の実コードなのか。
によって実コードに対する捉え方や理解の仕方が変わります。