初めまして。
今年度新卒でSier企業に入社したhirotoです。

今回は全てのエンジニアの耳にタコができるほど取り上げられている、変数や関数の命名についてです。
入社して半年ほど経ち、上司にレビューをしていただく中でご指摘された2つのポイントを備忘録としてまとめたいと思います。

1. 抽象的な単語を使うべからず

これは当たり前すぎることかもしれませんが、関数の命名に抽象的な単語を使ってしまっていました。

抽象的な単語の例としては、「check」や「validation」や「calc」などが代表的かと思います。

コードを書いているときの私は、可読性などお構いなしでノリノリになってしまう傾向がありました。
私がレビュー以前に書いていたコードには、上記のすべての単語を使ってしまっており、
「コードを見ても何の処理を行っているのかが分からない」と言われてしまいました。

これらの抽象的な単語を使わない代わりに、「isEmpty」や「extractTitle」などの具体的な命名をすることで
関数名から何の処理を行っているのかを明確にすることが大切だと学ぶことができました。

2. 一行で書くことが正義とは限らない

私は何でもかんでも、短く処理を実装することがかっこいいと思っていました。

私が突っこまれたコードは下記のような複合条件式でした。
if 0 < day <= 31 and 0 <= hour <= 24:

コードを書いた私としては、これくらいなら読めば理解してもらえるだろうと思って書いてしまいました。

です赤の他人がこのコードを見ると、理解するのに時間がかかったり、
正しく理解されないことがあるといったご指摘を受けました。

この対処法としては、複合条件を避けてあえてifをネストさせる (ネストが深くなり過ぎないように注意する) ことや、
さらに可読性といった面では何の処理を行いたいのかを明確にするために、関数化して名前を付けることでレビューが行いやすくなるといったことが学べました。

まとめ

今回の件では、レビューに掛かる時間の削減や保守性を担保するために

可読性というものがどれほど大事かを学ぶ良い経験ができました。

Qiitaを見ていて同じような事を書かれている記事を何度も拝見したことがありますが、
実際に当事者になってみると自分もやらかしてしまっていましたので、
今回は自分の為の備忘録として書かせていただきました。

初めての投稿ということもあって、情報量も少なく拙い文章だったかと思いますが
今後はQiitaを学んだことをアウトプットする場として活用していこうと思いますのでよろしくお願いします。

最後までご覧いただきまして、ありがとうございました。