コメント、書いていますか？
僕はコメントを適度に書いています。
ここでいうコメントは、
// 定数
のように、「ここは〇〇を書くブロックですよ〜」と指し示すものではなくて、
// 現状仕方なくこうしています
という、補足説明をするためのコメントです。
コメントを書く基準
基本的には、コードを読んでわかるよう記載、設計にする。
という方針でコードを書いてるつもりですので、必要以上にコメントを書き込むことは無いですが、仕方なく特殊な実装をせざるを得ない場合など、コメントを書くようにしています。
そのように方針を決めていますので、レビューでも「ここはコメントを書いては？」と提案します。
すると、メンバーから「コメントを残すルールを決めたい」という意見が出てきました。
確かに、個人的な基準をきちんと整理して、チーム内でルール化できれば、最適な開発ができるかもなと思い、ルール化することにしました。
現状、うまく活用できているため、紹介いたします。
コメントルール
| コメントアノテーション | ルール |
|---|---|
| TODO | リリースまでの開発で利用可能 |
| FIXME | 既知の不具合がある ※不具合のチケット番号を記載 |
| REFACTOR | リファクタリング ※リファクタリングチケット番号を記載 |
| NOTE | 任意のコメント |
FIXMEとREFACTORのルールにて、チケット起票漏れを防ぎます。
TODOは、開発中のみ利用を許可しました。リリースするタイミングで残っていることは禁止です。
Github actionsでmainブランチに向けてPR作成時、TODOが残ってるとコメントされるようにするつもりです。（実装を忘れていた。やらねば。。。）
vs codeの拡張機能で、todo treeというものを教えてもらいました。便利！
https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree
NOTEは、任意コメントのため、コメントとして残すべきかどうかをしっかりとレビューし、必要がなければ削除するようにしました。
参考
個人的に、以下記事のアノテーションを利用していましたので、ルール設定の際に参考にさせてもらいました。
以上です、みなさま、よきコメントライフをお過ごしください。