はじめに

チーム内リーダブルコード輪読会の第5･6章。
第4章はこちら

第5/6章　コメントすべきことを知る/コメントは正確で簡潔に

どんな内容？

５章

　１．コメントすべきでは「ない」ことを知る
　　・コードを読んですぐに分かることはコメントにする必要がない
　２．コードを書いているときの自分の考えを記録する
　　・手法について、採用理由を説明する。
　　・コードの欠陥、不足については記法(TODO/FIXMEなど)に則って記載する。
　３．読み手の立場になって何が必要になるかを考える
　　・読み手が疑問を感じるような処理についてはコメントを残す。
　　・ファイルやクラス単位で「全体像」(仕様レベルで)の記述を行う。

　　第５章では"コメント"ってどんなことを書くべきなのか。どんなことを書くべきではないのか。
　　また、コメントで教えるべき情報なのか、ソースを直して対応すべきなのか、方針論についてまとめられていた。

６章

　１．指定先が曖昧な代名詞(「それ」「これ」など)の使用を避ける
　　・// これはAAAを返却する関数です。(←記載位置によっては指している対象が分かりにくい)
　　　→ // testFunctionはAAAを返却する関数です。
　２．関数の動作は正確に説明する
　　・// ファイルに含まれる行数を返却します。(←何も記載がない時や１行だけの時は？)
　　　→ // ファイルの"\n"の数を返却します
　３．コメントに含める入出力の実例を慎重に選ぶ
　　・正規表現だったり、実際のパターンだったり、必要な情報をむしろ値として示す。
　４．コードの意図は詳細レベルでなく高レベル(仕様レベル？)で記述する
　　・詳細レベルでソースの動きを説明するよりも、何をしたいのか、を記載した方が後から読むには分かり易い。
　５．よくわからない引数にはインラインコメントを使う
　　・引数がどういった意図で渡されているのか、その内容はどんな単位なのかなど必要な情報はインラインコメントで残す。
　　　ex)　

testFunc

  testFunc(/* timeout_ms = */ time, /* use_encryption = */ false);

　　　　　 timeoutはmsで補助的に時間の単位が何であるかという情報を付与している。
　　　　　 use_encryptionは手前につけることで意味が通り易い。後部につけるとuse_encryptionがfalseなのか、
　　　　　 falseがuse_encryptionなのか分かりにくくなる。
　６．多くの意味が詰め込まれた言葉や表現を使って、コメントを簡潔に保つ
　　・分かりにくくなる冗長な表現よりも、共通的に認識された短い言葉のほうが分かり易い。

　　第６章では実際にコメントを付ける際に、具体的にコメントを付けるならどうする？と言う観点で、
　　第５章で示された方針をさまざまなケースごとにどう活かすか記述されていた。

読んだ感想

第５章

　自分自身、コードを書いていてコメントを付けるのは「機能の説明」をしようとするものがほとんどだったことに気が付かされた。
　「ひどいコードはコメントを無理につけるよりコードを修正する」と言う段については今まで全く内に考えがなかったように思う。
　また、個人的には定数の「背景」を説明するコメントを付けるという考え方はなかったので非常に興味深かった。
　

第６章

　最も勉強させられたのは、関数の機能を説明する際に実例を記載してしまうと言う手法だった。
　今までは頭の中にコメントと言うのは自然言語レベルで、機能の説明を行うものと言う意識が何処かにあったのだと思う。
　また「多くの意味が詰め込まれた言葉や表現を使う」為には、より最新のスタンダードを吸収し続ける必要性があると解釈した。

　あとは6章の扉絵が簡潔に印象的で非常にこの章で何を学ぶのか、が分かり易かった。

例

　分量が多いので、２例に絞って議論を行いたい。

１．実例をコメントに付与する

　実例をコメントに付与する場合について例を抜粋する。

StringUtil

 // 'src'の先頭や末尾にある'chars'を除去する。
 String Strip(String src, String chars){...}

↓

StringUtil

 // 'src'の先頭や末尾にある'chars'を除去する。
 // 実例：Strip("abba/a/ba", "ab")は"/a/"を返す
 String Strip(String src, String chars){...}

　あまりここでは見ない方式のコメントだが(Utilは極力作らないと言うことは置いておいて)、
下手に解説をコメントに書くのも長くなるけどソースは長大な処理だし、と言う場合など、
結局○○を返すんだよって記述は有用性が有るように感じた。

２．コメントの付与ではなくコードを修正する

　個人的に気が付きが大きかった、コメントをつけると言う本題とは逆に
「ひどいコードはコメントを無理につけるよりコードを修正する」
部分について以下、例を抜粋。

RegistryManage

 // レジストリキーのハンドルを解放する。実際のレジストリは変更しない。
 void DeleteRegistry(RegistryKey key)

↓

RegistryManage

 void ReleaseRegistryHandle(RegistryKey key)

　コメントを足すのか、リファクタするのか、実際に後から対応する時に指針になると感じる。
　特にリファクタだとしてもメソッド名のリファクタだけなら
影響範囲もそこまで広くない(処理内容自体は変わらない)ので、
手段として先々使っていくことが出きると思う。

コメントはあくまで"補助"と言う部分を意識して、
コードは適切な形にした上で、尚解説があった方が良い部分に付与することが肝要と解釈した。

　後はまとめにある通り。