やぎしんぶろぐ

〜とあるC#プログラマーのブログ〜

コードのコメント文の書き方について

皆さんお久しぶりです。笑

昨日、同期の川村くんに”お前、ブログ止まったな”って言われたので、溜めてたネタ出していきます。笑 (勝手に名前出してごめんな)

 

さて、先日以下の本を買いました!(といってもデブサミの時だから2月18、19日か。)

 

www.oreilly.co.jp

 

この本には、コードを書く上で成果物の品質をどこで高めていくか、というところのエッセンスがたくさん書かれています。

抜粋すると、

  • 変数の命名力向上
  • ”1行で書く複雑なロジックでどやぁ” よりも ”簡単に理解できる複数行のコード”(C#で例を挙げると、LINQを思い浮かべます。)
  • コメントの書き方~そこでコードに想いを込める~
  • タスクの細分化をコードベースやる方法

もっといろいろあるんですけど、この本で学ぶことは中々に多かったです。

 

・・・で、先日尊敬する先輩社員の方にソースコードレビューをしていただいたんです。

結構自信ありげに「お願いします!」って言ったんですが、レビュー指摘の中にこんなものが。下記、そのまま引用です。

 

コメントの書きっぷりについて

コーディングの内容をそのままコメントとして書くのは、

メリットより、デメリットの方が多いと思うので、私的にはあまりやらないようにしています。

コーディングとコメント、両方メンテナンス対象になるため。

私的な「そのままコメント」を書く指針としては、以下の感覚です。

  • そのままコメントがいらないように、極力シンプルにコーディングできないか検討する
  • (考えてもダメなくらい)実装がすごく複雑である場合は、必要な分だけコメントを書いておく(全てはなるべく書かない)。

コメントに関しては、諸説あるので一概には言えません。

なので、意見の一つとして参考にしてもらえればと。

 

この内容、まさにあの本に記載されている内容のことを指摘されてしまいました。

うわー・・・と。自己レビューで気付かないくらいそんなに焦ってたかなーと。

 

コーディング&コメント書いてて、”ただ何の気なしに書いたコメント”程、可読性が下がるものはないなということを身をもって感じました。

また、コードレビューで指摘される内容が、徐々にリーダブルコードに書いてある内容に近づいてきた(つまり、コーディングの指摘ではなくなってきた)ので、自分の日々の成長も少しだけ実感することができました。

 

 

コメントって難しいなー。最近コードで時間を掛けてしまうのが、変数とメソッド共通化検討。それにコメントが加わってきたら、今後自分の工数はどこまで膨れ上がっていくのでしょう・・・。QCDのバランスをみて、”早く、質の高いコメントを残せる”ように!これは、慣れ?笑