５
「コメントすべきことを知る」を
まとめていきます。
目次
<li>
<a href="#i-2">読み手への意識</a>
</li>
<li>
<a href="#i-3">まとめ</a><ul>
<li>
<a href="#i-4">①見たらわかるやん！というコメントはしない。</a>
</li>
<li>
<a href="#i-5">②コードの補足情報をコメントしない。</a>
</li>
<li>
<a href="#i-6">③プログラムの不満を書き残す。</a>
</li>
</ul>
</li>
<li>
<a href="#i-7">所感</a>
</li>
４章はこちら
読み手への意識
コメントを残すということは、
読み手に何か伝えたいことがあるはずです。
それは、自分かもしれないし、チームメンバかもしれない。
伝えたいことが伝わらないコメントは、
プログラム自体の可読性を下げます。
まとめ
①見たらわかるやん！というコメントはしない。
For i=0 To 3 ’三回繰り返す。
next
→書くのであれば、なぜ三回繰り返すのか、
プログラム全体を通した内容の要約を書く！
②コードの補足情報をコメントしない。
例えば関数名が分かりにくいコードに対する補足的なコメントを書かない。
→関数名を変更する。
そもそも綺麗なコードは可読性が高い。
綺麗なコード ＞ 汚いコード ＋ コメント
③プログラムの不満を書き残す。
プログラムは書いていく程に進化します。
書き終わってから、効率的なプログラムを思いつくが、
時間の制約がある場合など多々あると思います。（私はよくある。
下記のよう記法で不満を書き残しましょう。
- Todo:
- 後で手をつける。
- Fixme:
- 既知の不具合
- Hack:
- あまり綺麗じゃない解決策
- XXX:
- 危険！大きな問題がある。
所感
読み手への意識やそもそも綺麗なコードを書くなど、
抽象的な内容？で、（ちょっと表現が違うかも
一朝一夕では改善できなさそうな内容ですね。
しかし、読み手を意識するという本質させ抑えていれば、
自ずと改善出来そうです。
もちろん、読み手へ結果のヒアリングが無いと独り善がりになってしまいますけどね。
（読みやすいコメントを記載できているのか？第三者の目が必要）
全ての事に言えますが、
俯瞰的な目線と文字や対面含めたコミュニケーションは大事だなーと
思いまっした。
リンク