コードから読み取れる情報をコメントに書くべきではない

ここ2,3年、同じチームの若手に口を酸っぱくしてフィードバックしている内容に、「追加情報のないコメント・descriptionを書くべきでない」というものがあります。

追加情報のないコメント・descriptionとはなにか

例えばコードならこんな感じです。

int apple_count = 10; // りんごの数

terraformなら以下のような感じ:

resource "aws_wafv2_web_acl" "cloudfront" {
  name        = "cloudfront"
  description = "for cloudfront"
}

なぜ書くべきではないか

追加情報のないコメント・descriptionは何もメリットがありません。
上記のCコードでもterraform設定ファイルでも、変数名やnameで得られる情報とコメント・descriptionで得られる情報は全く同じです。なのでコメントを書いても何も嬉しくありません。

嬉しくないどころか、デメリットばかりあります。行数が増えて可読性が下がり、同じ情報の二重管理になるため更新漏れが発生します。

なので、僕はコメント・descriptionと変数名などについて以下のようによく言っています。

極力変数名やリソース名だけでそれがなにかわかるよう名前をつけるべき。
それで名前が長くなっても、短く分かりづらい名前よりはほとんどの場合マシ。

名前で伝えられないコンテキストや背景、whyを残すときのみdescriptionやコメントを使うべき

具体的に問題が発生した例

次のコードは実際に今日発見したterraformコードです。

output "web_acl_global_arn" {
  value       = aws_wafv2_web_acl.private_global.arn
  description = "web acl グローバル"
}

output "web_acl_tokyo_arn" {
  value       = aws_wafv2_web_acl.private_tokyo.arn
  description = "web acl グローバル"
}

このコードは間違っています。具体的には、8行目の2つ目のリソースのdescriptionです。
こちらはtokyoリージョンのweb aclであるため、

  description = "web acl リージョナル(東京)"

と書くべきところを、コピペ後に変更を忘れていたために

  description = "web acl グローバル"

とコピペ元のままになってしまっています。

そもそも、このdescriptionはoutputの名前を日本語訳しただけでoutputを利用する側になんら付加情報を提供していません。そもそも書かなければ書き換える必要もこのようなミスも発生しなかったのですが、descriptionを書いてしまったせいで間違いが発生し、この間違いによりさらにこのoutputが果たして名前通りのものなのか、それともdescriptionのほうが正しいのか、といった無用な混乱さえ引き起こしています。

スポンサー

この記事はSpeeeでの業務中に15分で書きました。