こんにちは。aliceです。

有名な『リーダブルコード』

第６章「コメントは正確で簡潔に」を読んだのでまとめてみました。

が、あんぱんの話しか書いていません。サブタイトルは「コメントとあんぱん」です。

あんぱんを買ったり食べたりしたことがある方。

おめでとうございます！

もうすでに正確で簡潔なコメントができていますよ！

１　コメントは簡潔にしておく

１行で説明できることに３行使わない

朝あんぱんを食べたんだ～と言いたいときに

ねぇねぇ聞いて
今日起きたらなんか甘いものが食べたい気分になって
何がいいかな～と思ってスマホをしていたらパンが食べたいな～と思って
朝一でパン屋さんに行ったらあんぱんがあったから買ってきて食べたんだ～

というよりも

今朝あんぱんを食べたよ

の方が伝わります。

説明は簡潔にしましょう。

２　あいまいな代名詞を避ける

「それ」や「あれ」などの言葉は、何を指すかわからないこともあるのでを使わない

あんぱんを買いたいときに

そのパンをください！

とはあまり言わないですよね。

「そのパンってどのパン？？」となります。

あんぱんをください！

と言います。

対象が複数あるときは「それ」や「あれ」を使うとわかりづらくなるので、使わないようにしましょう。

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

コメントを正確にすることと簡潔にすることは両立することが多い

あんぱんを買いたいなというときに

あんぱんが売っているかを確認し、買うか買わないかを判断する

だと、うーん、ちょっと何言っているかわかりづらい

あんぱんが売っていたら買う

の方がしっくりきます。

スッキリした文を書きましょう。

４　関数の動作を正確に記述する

実装に適したコメントは伝わる情報が増える

パン屋さんでのお支払い。

この財布の中にある紙の枚数を数える

これだと紙幣の枚数を数えているのか、レシートなどを含んだ紙の枚数を数えているのか、人によって解釈がかわります。

この財布の中にある紙幣の枚数を数える

これだと紙幣の枚数を数えるとわかります。

動作は正確に書いた方が伝わりやすくなります。

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

入出力の実例をコメントに書いておけばそれは千の言葉に等しい

パン屋さん。今日はセールです。

あんぱんセット２０％オフ

と書いてあるよりも

あんぱんセット２０％オフ　
１，８００円⇒１，４４０円

と書いてあった方がどんな計算をしているのかすぐにわかります。

ちょっと難しい関数のときは、入出力の実例を書いておくと、ぐっとわかりやすさが増します。

６　コードの意図を書く

コードの動作ではなく意図を書く

パンを食べていることを伝えるときに

まず、パンをつかむ
そのあとに肘を軸に腕を回転させ口までパンを運ぶ
口の前にパンが来たら口を開ける
パンを口の中に入れる
歯を動かしパンを噛む　ということをしているよ

と言われると「ん？何のこと？？」となりますよね。

その場合は

パンを食べているよ

で十分です。

実際の動作を書くより意図を書いた方が伝わることもあります。

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

インラインコメントを使って引数を名前付きで渡す

パンを買うときに

上から６個めに置いてあるパンをください

と言うよりも

あんぱんをください

と言った方がすぐにわかってもらえます。

名前がわかりづらいときはインラインコメントを使いましょう。

８　情報密度の高い言葉を使う

多くの意味を含んだ言葉を使う

あんぱんを買うときに

小豆などの豆を煮てつぶし、砂糖や塩を入れ、さらに加熱して練ったものが入っているパンをください

とは言わないですよね。

あんぱんを知っていたら

あんぱんをください

これで伝わります。

「あんぱん」という言葉には「あんこ（小豆などの豆を煮てつぶし、砂糖や塩を入れ、さらに加熱して練ったもの）が入っているパン」という意味を含んでいます。

多くの意味を含んだ言葉を使いましょう。

もとは昨日参加したノンプロ研のリーダブルコード輪読会です。

１～５章まではこちらをどうぞ

輪読会は初めてだったけど楽しかったです。

いろんなアプローチの仕方があって、勉強になりました。

あんぱん食べたくなってきた。

おしまい。