5章コメントすべきことを知る

本章の目標は、コメントすべきことを知ってもらうことだ。コメントの目的は「コードの動作を説明する」ことだと思っているかもしれない。でもそれは、目的のごく一部でしかない。

[Tip]

鍵となる考え

コメントの目的は、書き手の意図を読み手に知らせることである。

コードを書いているときには、君の頭のなかに大切な情報がたくさんあると思う。でも、誰かが君のコードを読むときには、その情報は失われてしまう。コードを読む人が持っているのは、目の前にあるコードだけだ。

本章では、頭のなかにある情報をいつ書き出せばいいのかという例を数多く紹介している。コメントに関してよく言われるようなことには触れていない。もっと興味深くて「注目されていない」側面に集中した。

本章では、以下の話題を取り上げる。

  • コメントするべきでは「ない」ことを知る。
  • コードを書いているときの自分の考えを記録する。
  • 読み手の立場になって何が必要になるかを考える。

5.1 コメントするべきでは「ない」こと

Get リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.