コメントを書くときに気をつけたいこと

Jun 7, 2019   #code  #readable 

リーダブルコードを読んだ。 確か、この本は1年半ほど前に購入してサラっと読んで それっきり読んでなかった。

久しぶりにちゃんと読み返してみた。

コードは他の人が最短時間で理解できるように書かなければいけない。

たとえ自分ひとりのプロジェクトだったとしても、「他の人」は自分のコードに見覚えのない6ヶ月後の「自分自身」であるかもしれない。

小さいことがいいこととは必ずしも限らない

コードは短くしたほうがいい。だけど、理解する時間を短くするほうが大切。

コメントは自分の考えを記録する

自明であることをコメントとして書く必要はない。

本書では例として以下のように取り上げられている。

// このクラスは汚くなっている
// サブクラス `ResouceNode` を作って整理したほうが良いかも

これをより使い分けるためには

TODO:  (あとでやる)
FIXME: (既知の不具合があるコード)
HACK:   (あまりキレイじゃない解決策)
XXX: (危険 / 問題がある)

などを使う。

定数にコメントをつける

NUM_THREADS = 8 # 値は「>=2 * num_processors」で十分

というコメントがあれば定数が決まった背景が理解でき、 これ以上調整する必要がないことがわかる。

新しいチームのメンバーの気持ちになる

新しいチームメンバーにとって最も難しいのは「全体像」の理解である。 クラスはどのように連携しているのか。デーアはどのように流れているのか。

例えば以下のような会話があったとする。

「このクラスは複雑だが、単なるキャッシュです」

これはソースコードを読んだだけでは得られない情報である。 本書はこれをコメントとして書くことを推奨している。

私自身は小さなプロジェクトであればREADMEなどに ディレクトリ構造(tree)を図示するなどし、簡潔な説明を付け加えるなどでも良いと思う。

標準のライブラリを知る

標準のライブラリを知らないがために 自分でスクラッチで実装してしまうことも少なくない。 少ない行かつ簡潔でわかりやすいならそちらを優先する。

リストから重複する値を削除したいとする。 その場合は関数を作るよりもPythonのSet(集合)を使ったほうが 容易に実装できる。

テストコードを読みやすくする

大切な情報は目立つようにし、そうでない情報はユーザから隠す。

具体的にはヘルパー関数を作ったりする。

テストの本質は「こういう状況でこういう入力からこういう振る舞いと出力を期待する」というレベルまで要約できることである。さらに、これは少ない行で簡潔に表現できることが多い。

まとめ

コメントにはWhatではなく、Whyを書くべきである。

設計のミスに気づくのはテストコードを書くことがやはり大切。