はじめに
今回はアノテーションコメントについて。
コメントを書く際に、アノテーションコメントについて知らなかった(TODOやFIXMEなどは聞いたことがあったが、他に存在しているものが多くあった)、使えていなかったことがあったのでまとめればと思います。
アノテーションコメントとは
アノテーションコメントとはコメントにメタデータを付加するもの。
アノテーションキーワード
# TODO: 不足している機能や、後日追加すべき機能を記す
# FIXME: 修正が必要なコード
# OPTIMIZE: パフォーマンスの問題を引き起こす可能性のあるコードや非効率なコードを記す
# HACK: 疑わしいコーディング方法が使用されていたコードの匂いを記す
# REVIEW: 意図した通りに動作しているかどうかを確認するためにレビューすべきもの
他にも
# XXX: 危険！ 大きな問題がある
# CHANGED: コードをどのように変更したか。
# NOTE: なぜ、こうなったという情報を残す。
# WARNING: 注意が必要。
アノテーションコメントを書く場所
# bad
def hoge
baz(:quux) # NOTE:
end
# good
def hoge
# NOTE:
baz(:quux)
end
アノテーションコメント フォーマット
キーワードの後には、コロンとスペースを入れましょう。
# bad
def bar
# NOTE
baz(:quux)
end
# good
def bar
# NOTE: hogehoge
baz(:quux)
end
アノテーションコメント一覧をターミナルで表示する方法
検索したいキーワードを入力することで、任意のものが表示されます。
$ rake notes
$ rake notes:custom ANNOTATION= アノテーションキーワード
最後に
アノテーションコメント一を用いることでレビューしていただく人、後からチームにジョインされる方にとって疑問を解消する手助けにもなったり、レビューの負荷を下げることができるので積極的に使っていきたいですね。ただ何でもかんでもコメントを使いましょうというわけではなく、コードで解決できることが一番だと思うので、そこは念頭に置いてやっていければなと思います。
参考
The Ruby Style Guide
https://rubystyle.guide/
TODO: 以外のアノテーションコメントをまとめた
https://qiita.com/taka-kawa/items/673716d77795c937d422