🙄
これが俺の最強アノテーション
Daily Blogging38日目
Tidy First?読んでます
コメントって結構書く内容が人によってまちまちで、質の担保難しいですよね
結論
これで大丈夫
| アノテーション | 意味 | 用途 |
|---|---|---|
| CONTEXT | コードの背景や文脈 | コードが存在する理由を説明する。 |
| TRADEOFF | 設計や実装のトレードオフ | 性能、拡張性、保守性など、選択肢を比較した際のトレードオフを記録する。 |
| WARNING | 注意が必要な箇所 | パフォーマンスなど発生する可能性のある問題点などを記述する。 |
良いコメントとは
よくいうのが、「コードで表せないこと」をコメントに残すということ
コードに書いてあることをコメントで書いてもそれはただ冗長な行が増えるだけ
これは書く必要がない、むしろ書くことによってコードリーディングの時間を増やしてる悪い例
# ユーザーの名前を取得する
user_name = user.name
t_wadaさんは、「コメントにはwhy not」を書こうって言ってる
アノテーション
コメントには、いくつかのアノテーションが存在してる。
| アノテーション | 意味 | 用途 |
|---|---|---|
| TODO | 後でやる | 将来的に実装や修正が必要な箇所を示します。 |
| FIXME | 既知の不具合 | 現在のコードに問題があり、修正が必要であることを示します。 |
| NOTE | なぜこうなったか | 特定の実装が行われた理由や意図を記述します。 |
| HACK | 要リファクタ | 一時的または強引な実装で、将来的に改善が必要な箇所を示します。 |
| REVIEW | 意図した動作がレビュー必須 | コードやロジックが正しいかどうか、レビューが必要な箇所を示します。 |
| WARNING | 注意 | コードの使用に関して注意が必要な箇所を強調します。 |
| OPTIMIZE | ボトルネック | パフォーマンス改善が望まれる箇所を示します。 |
| XXX | 危険！問題がある | 深刻な問題や不安定な箇所を示します。 |
| CHANGED | どう変更したか | 変更履歴や改修内容を簡潔に記述します。 |
アノテーションを使うことで次のメリットがある。
- 書き方の統一ができる
- そのコメントが何を指しているのかが明確
- 書くべきことがわかる
アノテーションの問題点
とにかく使い分けが面倒くさい
そんなにたくさんあってみんな使ってるの？？
うちはMEMOとTODO、時々FIXME
MEMOには色々書き、TODOとFIXMEは解消されることなく溜まる一方
やばいっ
うちの場合、とくにメンバー変更が激しいので仮にアノテーションをたくさん使うルールにしてもそんな浸透しない。
あと使い分けが大変。
XXXとかいつ使うん？
OPTIMIZEとか望んでる場合じゃない
じゃあどうする？
アノテーションのメリットもわかる。
特にアノテーションを利用することで、コメントにはこう言ったことしか書いちゃいけないんだってなる。
じゃあこの要件を満たすアノテーションにしたらいいんじゃないのか
- アノテーションの数を最小限にする
- 使い分けが簡単
- コメントとして必要なもの
結論（２回目）
コメントに書くことって大体これ
- なんでそのコードが必要なのか
- パフォーマンスの観点から見た問題点
- 今後こういった問題が発生するかも
だからこの３つのアノテーションでいけるはず。
| アノテーション | 意味 | 用途 |
|---|---|---|
| CONTEXT | コードの背景や文脈 | コードが存在する理由を説明する。 |
| TRADEOFF | 設計や実装のトレードオフ | 性能、拡張性、保守性など、選択肢を比較した際のトレードオフを記録する。 |
| WARNING | 注意が必要な箇所 | パフォーマンスなど発生する可能性のある問題点などを記述する。 |
これならt_wadaさんの「why not」の部分もカバーできる
Discussion