コードに書くべきコメントとは?

エンジニアHub さんの記事がすごい良かったです。

Rubyコミッター・Yuguiに学ぶ、コードに書くべき「適切なコメント」と「適切な場所」

基本的なスタンスは、次の文に現れていますね。

殆どの命名やコードは自明であるべき」と思ってるのでどうしても自明に出来ない箇所にコメントを書くようにしてる。ただし書く時には数十行書く時もある。自明な部分に対するコメントはあまり意味がない。

コーディングをいくら頑張っても伝えきれない部分ってありますよね。
コメントとして書くのは、そういうことを拾い上げて書いてあげることが大切です。

こんなものは、自明すぎるのでほとんど意味がありません。

// Hoge を実行して true になることを確認する
$this->assertTrue($hoge->execute());

どうせコメントするなら、もっと上の視線で書いてあげることで理解を助けるコメントになります。

他者がそのコードを利用することを前提として、コードだけでは伝え切れない情報を付属的に伝える。

必要なのは、「他者から見てどうなのか」を意識することです。
「半年後の自分が読んだ時に理解できるか」考えることです。

その他参考

良い?悪い?コードコメントの書き方

[プログラミング]そのコメント、カッコ悪い
https://atuweb.net/201605_how-to-put-comment-is-wrong/

スポンサーリンク







シェアする

  • このエントリーをはてなブックマークに追加

フォローする

スポンサーリンク




コメントの入力は終了しました。