2016.11.30
リーダブルなコードを目指して(その2)
エンジニアの時間でコードを書く以上に、コードを読む時間のほうが多いことがしばしばあります。
コードを読むときに参考となるのがコメントです。が、コードを理解する助けになるコメントとはどのようなものでしょうか？
悪いコメントとは
良いコメントがどういうものか考える前に、良くないコメントとはなにかをあげてみたいと思います。
01．コードを見た瞬間に内容がわかるコードについたコメント
public function __construct() {}
// 支払額を設定する
setPayment($money);
上の２つはコードを見ればなにをしているのか一目でわかるため、コメントを付ける意味はありません。
02．良くない内容を説明するためについたコメント
// 入力されたテキストからHTMLタグを取り除く
processText($html)
こちらのメソッドはそもそも名前から処理内容が伝わってこないため、removeHtmlTag($html)のように名前を変えましょう。
コメントがなくても理解できるようになります（大規模なコードのときは変更時の影響が大きすぎて名前を変えられないという事情があったりもしますが……）。
良いコメントとは
悪いコメントから逆に考えると、『見た瞬間ではわかりづらいコードに、どのような意図があるのか』が書かれたものが良いコメントの１つと考えられそうです。
たとえばどのようなものでしょうか。
// コードが肥大化している
// URLの解釈部分を別メソッドに分割したほうがいいかもしれない
downloadFile($url)
// TODO: 古いバージョンのライブラリを使っているため、最新バージョンに変える
上記のコメントはコードを読み解いた、読む前の事前情報として有用となります。
// ブログの記事一覧は件もあれば十分
MAX_VIEW_POSTS = 20
こちらは定数にコメントを付けたものとなりますが、コードを初めて読む人にとっては20という数値がわからないため、こちらも知ってもらいたい意図を伝えているコメントになります。
まとめ
コメント適切につけることで、読みやすいコードになります。
読みやすいコメントをつけたからといって自分は得しないという意見もありますが、自分で読み返す可能性もあるため、わかりやすいコメントに配慮することは重要だと思います。
最後に紹介するのは、筆者が遭遇したコメントです。
// なんか知らないけどとにかく動く
// 触りたくないから誰か直して
こんなコメントが今もどこかに残っているのです。たぶん。