Help us understand the problem. What is going on with this article?

読書まとめ:リーダブルコード 第5章

More than 5 years have passed since last update.

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

  • 読み手が細部に捕らわれないように、コードブロックにコメントつけて概要を書く

  • ファイルやクラスには全体像のコメントを書く

  • 定数の値にまつわる「背景」を書く
    なぜこの値になったかを書く。

  • 平均的な読み手が驚くような動作は文章化してコメントとして書く
    なんでこんな処理しているんだろうと疑問に思いそうなところに書く。

  • コードを読んだ人が疑問って思うところを予想してコメントを書く

  • なぜコードがこうなっているのかを書く(監督コメンタリー)
    他のやり方(ロジック等)でなくこうなっているかを書く。

  • コードの欠陥をTODO:やXXX:などの記法を使って表す

記法 意味
TODO あとで手を付ける
FIXME 既知の不具合があるコード
HACK あまりきれいじゃない解決策
XXX 危険!大きな問題がある

補足
コメントすべきではないこと
・コードを読めば理解できる内容
・ひどいコード(例えばひどい関数名)を補う「補助的なコメント」
その場合はコメントではなくコードを直す。

所感

今まで書いていたコメントは、コードの内容を記載して重要な情報が不足していたように感じる。
上記のポイントを意識して書く訓練を行う。

kiyomaru
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away