📖
【リーダブルコード】明確で簡潔なコメントを書く
※ 下記のリンクにある本の韓国語版を読んで簡単に整理しました。
明確で簡潔なコメントを書く
いい加減な文章は整えよう。コメントを明確にし、簡潔にする作業はたいてい同時に行える。
曖昧な説明よりも、目的を明確に
// このURLを以前に訪問したかどうかによって、優先度を変える
一見、問題のないように見えるが、以下のように書き換えることで意図が明確になる。
// まだ訪問していないURLに高い優先度を与える
前者は状況を説明しているだけだが、後者はそのコードの目的を明示している。
こういった小さな違いが、読み手の理解度に大きな差を生む。
入出力の例でコーナーケースを説明する
// 'src' の先頭と末尾から、'chars' に含まれる文字を削除する
String strip(String src, String chars) {
// 実装は省略
return "";
}
このようなコメントに加えて、次のような入出力の例を追加すると効果的：
// 例: strip("abba/a/ba", "ab") は "/a/" を返す
String strip(String src, String chars) {
// 実装は省略
return "";
}
コメントで説明するのも重要だが、具体的な例は何よりも説得力がある。
他の人がコードの挙動を直感的に理解する助けとなる。
実例：日付フォーマット関数へのコメント追加（Java版）
// 例: 2022.08.20.
public static String formatL(LocalDate date) {
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy.MM.dd");
return date.format(formatter);
}
// 例: 2022年8月20日
public static String formatLL(LocalDate date) {
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy年M月d日");
return date.format(formatter);
}
これらの関数はフォーマットだけが異なるため、共通化もできるが、
それぞれの例を示しておくことで再利用時の理解が格段に早くなる。
時間が経った後に「これ何だったっけ？」となるのを防ぐには、こうした小さな工夫が効果的。
コメントは「読むための設計」の一部
良いコメントは、単に動作を説明するものではなく、
将来の開発者（＝自分自身を含む）に対する配慮でもある。
コードを読むときに、「この関数は何をしているのか」「どう使えばいいのか」が
一目でわかるようにするための補助線として、コメントを活用していきたい。
第6章の感想
この章では、「明確で簡潔なコメントを書くにはどうすればいいか」について、
実用的で今すぐ使えるテクニックが数多く紹介されていた。
- 説明は曖昧にせず、目的を明確に書くこと
- 入出力例を添えることで、挙動を直感的に伝えること
「読みやすいコードが良いコード」という考え方が、コメントにもそのまま当てはまることがよく分かった。
将来、自分や他人がそのコードに触れるときのことを想像しながら、読んでやさしいコメントを心がけていきたい。
Discussion