リーダブルコードの勉強会へ向けた資料作りとアウトプット Part5

公開日:2019-08-07
最終更新:2019-08-07

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

コメントの目的は、書き手の意図を読み手に知らせることである。
この章では普段あまり注目されていない側面から、必要なコメントはなにかを探っていく。

まとめ

コメントすべきではないことは以下二つ

  • コードからすぐわかること
  • ひどいコードの補助するコメント、ならばコードを変えるがよろしい

記録すべき自分の考えは以下三つ

  • なぜコードが他のコードではなくこうなっているのかを映画監督のように
  • コードの欠落をTODOやXXXなどの記法を使って示す
  • 定数の値にまつわる「背景」

読み手の立場になって考えるポイントは以下4つ

  • コードを読んだ人が立ち止まって「ん?」となる部分を予想してコメントをつける
  • 平均的な読み手が驚くような動作はコメントで明示する
  • ファイルやクラスには「全体像」のコメントをかく
  • 読みっ手が細部にとらわれないように、コードブロックにコメントをつけて概要をまとめる

ライターズブロックを乗り越える

ライターズブロックとは、コメントを書くのは大変だと思い込んで文章が書けないこと。まずは頭に思い込んだ注意点などを書き出してみることが大切だ。以下の三つの手順でまずは書いてみよう。

  • 頭の中にあるコメントをとにかく書き出す。
  • コメントを読んで(どちらかといえば改善が必要なものを見つける)
  • 改善する。
    最初からうまく書こうとしないことが重要だ。

読み手の立場になって考える

プロジェクトを熟知していない人にコードを見て、なにか質問されるだろうかと自分で一度考えてみる。例えば、このコードを見てビックリするところ、間違えて使われるかもしれない箇所を探す。そこに適切なコメントを入れる必要がある。また、全体像について短いコメントをファイルの最初に書くことも重要だ。関数を扱うときには、処理の要約をコメントにつけると分かりやすい。

自分の考えを記録する

映画監督のように
映画監督からのコメントのように、コードに対する大切な考えを記録する。例えば以下のようなコメントは大切だといえる。
//左右の比較よりもハッシュの計算コストの方が高いようだ。
コメントから情報を得られるので下手に最適化しようとする必要がない。
//○○だと○○が漏れることがある。100%は難しい。
このコメントがあれば失敗するテストケースをわざわざ作る必要がなくなる。
コードの欠落にコメントをつける
改善が必要な時はTODOコメントをつけよう
プログラマがよく使うこの手の記法は以下となる。
|記法 | 典型的な意味|
| ---| ---|
| TODO: | あとで手をつける|
| FIXME: | すでに分かっている不具合のあるコード|
| HACK: | あまりきれいじゃない解決策|
| XXX: | 危険! 大きな問題あり|
定数にコメントをつける
例えば定数の値を決めるにあたって、範囲や条件があるのかないのか分からなくなった経験がないだろうか。陥らないためにも、定数に値を決める範囲を残しておこう。

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

コードからすぐにわかることはコメントに書かない。
新しい情報を提供するわけでも、読み手がコードを理解しやすくなるわけでもない全く価値のないコメントはいらない。
コードを読んで理解する時間とコメントを読んで理解する時間のどちらかが早いかを天秤にかけるとよろしい。
コメントのためのコメントはしない
関数宣言とほぼ同じようなコメントはわざわざ書く必要はない。
ひどい名前はコメントをつけずに名前を変える
通常は補助的なコメントが必要になることはなく以下の式が成り立つ。「優れたコード>ひどいコード + 優れたコメント」

記事が少しでもいいなと思ったらクラップを送ってみよう!
0
+1
@NowBridgeがひたすらアウトプットします。

よく一緒に読まれている記事

0件のコメント

ブログ開設 or ログイン してコメントを送ってみよう
目次をみる

技術ブログをはじめよう

Qrunch(クランチ)は、ITエンジニアリングに携わる全ての人のための技術ブログプラットフォームです。

技術ブログを開設する

Qrunchでアウトプットをはじめよう

Qrunch(クランチ)は、ITエンジニアリングに携わる全ての人のための技術ブログプラットフォームです。

Markdownで書ける

ログ機能でアウトプットを加速

デザインのカスタマイズが可能

技術ブログ開設

ここから先はアカウント(ブログ)開設が必要です

英数字4文字以上
.qrunch.io
英数字6文字以上
ログインする