More than 3 years have passed since last update.

コメントにはhowよりもwhyを記述すると良い

Posted at 2021-07-22

先日、大手のエンジニアさんにコーディングテストのレビューをしてもらった。
その際に、"コメントは何をしているかよりも何故そうしているのかを記述すると良いです。"と
フィードバックを頂いた。

現在のインターン先に参加してから、多々"なぜそうしているのか"が分からずに苦労した経験があるため、whyの部分を書く方が良いなと納得した。

その後、頂いたフィードバックをインターン先のチームに共有した文章を、
ほぼそのまま載っけただけの内容です。

原則に従っていない書き方をする場合は
コメントは”何をしているか”よりも”何故そうしているのか”を記述する方が良い
（whyが不明な方だと初見の人にとって混乱を招き、様々なファイルを見て修正する必要が出てくるため）

↓バージョンを指定する明確な理由がある場合はその理由をコメントとして書いておく

Gemfile

# 4.6以上にするとxxxでエラーが発生する。以下のissueが解決したら最新版を使う
# https://github.com/plataformatec/devise/issues/9999999
gem 'devise', '~> 4.5.0'

# Reporting APIのデータが 0 の場合(サイトに誰も閲覧しなかった場合)はnilになるため、ぼっち演算子を利用
data = response.reports.first.data
data.rows&.each do |row|
   ...
end

# Reporting APIを叩く際に正規表現で抽出することでnilの可能性がない
# そのため、if文の外で実行している
page_view, unique_user_count = row.metrics.first.values[0..1].map(&:to_i)