川のブログ

川の適当気ままなブログです。 

リーダブルコードを読む part6

こんにちはかわです。

アドベントカレンダー21記事目です。

前回の続きです。

kawakawa.hatenablog.com

6章 コメントは正確で簡潔に

コメントは領域に対する情報の比率が高くなければならない

1 コメントを簡潔にしておく

少ない領域ですむように推敲する

2 曖昧な代名詞を避ける

代名詞はなるべく避けるように努める。

代名詞が何を指すかを明確にすべし。

3 歯切れの悪い文章を磨く

語彙力を磨く

4 関数の動作を正確に伝える

なるべく詳細に伝える。

コメントを読む人の誤解を減らすため。

5 入出力のコーナーケースに実例を使う

コメントが長文になる際には実例を使うべし。

ただし、簡単な実例では役に立たないので、

想定される質問に応えられる実例を書く。

6 コードの意図を書く

コードの動作をそのまま書くのではなく、高レベルから説明するのもあり。

その結果、コードが作者の意図に反しているかどうか見つけやすくなる。

7 「名前付き引数」コメント

pythonRubyなどは名前付き引数がある。

これはコメントのような効果があるため使ったほうがいい。

C++Java等はできないためコメントで実現する。

Connect(/* timeout_ms */ 10);

8 情報密度が高い言葉を使う

説明が長くなった場合、専門用語等を使用して短くできないか検討する。

以上

kawakawa.hatenablog.com