はじめに
コメントを種類ごとに分類できるアノテーションコメントを採用しています。
使っている内に経験的なベストプラクティスが自分なりにつかめてきたのでまとめてみました。
この記事でわかること
- アノテーションコメントの使い方と例がわかる
この記事の対象者
- アノテーションコメントを使いたいエンジニア
動作環境・使用するツールや言語
- Python3
- その他言語
アノテーションコメントとは
コメントの先頭にTODO: とかをつけて分かりやすくする試みです。
- コメントにメタデータを追加できる
- コードの欠陥が分かりやすくなる
よく使っている記法と意味
使って欲しい順に並べてみました。
レビュアー視点で思うことも書いています。
| 記法 | 意味 | 思うこと |
|---|---|---|
| INFO: | 関数の動作説明などの情報 | あるとなんだかんだ嬉しい (良い命名で省略できるかも) |
| NOTE: | なぜこうしたのか、こう考えたのかという情報 | コードからは読み取れない情報なのであると嬉しい！ |
| TODO: |
後で追加する機能がある 修正するべき機能がある |
終わったら消してね |
| HACK: | 汚いのでリファクタリングしたい | 直してからコミットして欲しい |
| WARNING: | 修正などには注意が必要 | なるべく使わずに済むようにして欲しい |
| FIXME: | 不具合が分かっているので修正する必要がある | 直してからコミットして欲しい。 修正したら消してね |
| XXX: | 何が起こっているのかわからない 危険な箇所 | 使わないで欲しい。 解決したら消してね |
TODO: より下は承認する時は(仕方ないな…)という気持ちが出てきます。
(現場のスケジュールもあるので辛い部分もありますが…)
その他CHANGED:とかもありますが、GitHubのdiffやPull Requestで分かると判断したので使っていません。
その他も統合可能だと思ってまとめています。
使用例(Python)
Pythonで例を出してみます。
python calculate_area.py
def calculate_area(radius):
# INFO: この関数は与えられた半径の円の面積を計算します。
# TODO: 半径が負の場合のエラーハンドリングを追加する。
# HACK: mathモジュールのインポート方法が分からなかったので、πを3.14として近似しています。
pi = 3.14
# WARNING: 近似しているので結果は若干不正確です。
# NOTE: 円の面積の公式は πr^2 。
area = pi * (radius ** 2)
return area
def main():
radius = 5
# FIXME: 入力のバリデーションをしてません。
print("円の面積は:", calculate_area(radius))
# XXX: この辺はネットからコピペしてきただけなので、なんで動いてるのか知りません。
for i in range(10):
print(f"イテレーション {i}: 面積 = {calculate_area(i)}")
if __name__ == "__main__":
main()
参考資料
まとめ
多少最初は手間ですが、スニペットや辞書に登録したりすると気軽かと思います。
VSCodeだとTODOS:TREEとかで一覧を出せて便利です。