理解できるコメントを書く
最近コメントの書き方で気をつけたいポイントを学んだのメモがてら書いてみます。重要なコメントを理解しやすい形で残せるようにしていけると、コードを通したチームのコミュニケーションだったり知見共有が円滑にいくと思うので上手にコメントを書けるようになりたいですねという記事です。
理解しにくいコメントを書くことが多い人生でした。
コメントの構成
- なんで？
- なんでそのコードが必要なのか
- これが必要な利用を書く
- 主文
- 対応内容についてのメインの説明コメント
- 参考など
- 参考になったリンクを書く
- なんの参考になったかも書くと良い
- 参考になったリンクを書く
まとめ
- 大事なことはあとから読んでわかること
- なんで？に答えられるコメントであること
- 読んだ人がわかるために、多少長くても良い