とりあえず、コメント書いとけば良いと思っているエンジニアを減らしたい

どうもやんてらです。

今回は技術的な記事ではなくて個人的に思っていることを書いていこうと思っています。 (内容は愚痴になりますので不愉快だと思われる方はブラウザバックをお願いします。)

今回取り上げた内容は「コメント」です。

ソースコードの中にコメントを書くという文化を否定したいわけではないのですが、メソッド名や変数名を特に考えずにコメントで補えば良いと思っているエンジニアに一言申し上げたくて記事にしました。

※サンプルのコードはrubyになります

def show_cost_per_click(ad)
  　ad_value(ad)
end

# 有効なad判別したい
def ad_value(ad)
  ad.cpc if ad.present?
end

↑のソースを読んで思ったことが何個かありました。

先ずはじめに、adの値メソッドの「戻り値が何なのか？」というのと「このメソッドでやりたいことって何？」ということでした。 コメントには有効なadの判別をしたいと書いてありますが、「本当にこのメソッド名で良いのか？」って私は思いました。

コメントを残す前に適切なメソッド名をつけて欲しいなと個人的には思っているので、 この場合ですと、available_adみたいなメソッドであれば凄くわかりやすかったです。この場合であればコメントも別に書かなくても英語を翻訳するだけでやりたいことは伝わるかなと思います。

個人的な良い例

def show_cost_per_click(ad)
  ad.cpc if available_click?(ad)
end

def available_ad?(ad)
  ad.present?
end

↑のような状態で補足したい場合も、もちろんあると思います。その時にこそコメントを残してくれればありがたいと思います。 しかし、そういう場合以外でコメントで補おうとしてしまうと次に改修する人のコストになってしまうので避けて欲しいなと思います。

個人的には変数名やメソッド名に悩めば悩むほどスッキリとしたコードになることが多いので、もっと変数名とメソッド名に意味を持して欲しいなと思いました。

(コードを書き始めて日が浅い人やリーダブルコードを読んだことのない人は一度読んでみて頂きたいです。

長文でしたが、最期までお付合い頂きありがとうございました。