RAKUS Developers Blog | ラクス エンジニアブログ

株式会社ラクスのITエンジニアによる技術ブログです。

分かりやすいコードを書いていますか?~他の人に優しいコードを書くポイント~

f:id:tech-rakus:20200507120912j:plain

はじめに

こんにちは。新卒2年目のnr_1228です。
ボリュームの大きい実装に携わるようになって、重要だと再認識したことがあります。

コードを書くときは、他の人(未来の自分も含む)でも理解しやすいように書くべき。

自分が書いたコードや既存のコードを読む際に、この変数は何が入ってるのだろう?となったことが何回かありました。

これはあの本を読み返すべきでは…
ということで、研修時に読んだ「リーダブルコード」を再び読むことにしました。
前回読んだ時よりも実体験などもあり、理解・納得できる部分が増えていました。 そこで今回は、改めて「リーダブルコード」を読んで、最近引っかかることの多かった命名のポイントロジックの単純化についてまとめてみることにします。

名前に情報を詰め込む

コードを書いていると名前を付けなければならない時が必ずあります。
関数や変数名を見た時点で、これは何をしている関数なのか、何の変数なのかが パッとわかるようにした方が、他の人にも親切です。

名前の付け方のポイントは以下の6点です。

明確な単語を選ぶ

その関数・変数が何を表しているのか明確にすることが、分かりやすい名前を付ける必須事項です。 自分の中ですぐに出てくる単語を使うのもいいですが、状況に合わせて単語を選ぶようにしましょう。

単語 代替案
send deliver, dispatch, announse, distribute, route
find search, extract, locate, recover
start launch, create, begin, open
make create, set up, build, generate, compose, add, new

汎用的な名前を避ける(あるいは使う状況を選ぶ)

戻り値にいい名前が思いつかなければ、retvalなどと付けたくなりますが、 「戻り値である」という以外の情報はありません。 戻り値として何を返しているのかが分かるような名前にしなければなりません。 例えば、xの2乗の合計を戻り値とするならば、sum_squaresというような名前を付けた方が retvalよりも変数の目的を伝えることができます。

抽象的な名前よりも具体的な名前を使う

ServerCanStartという名前の、任意のポートをサーバがリッスンできるか確認するメソッドがあるとします。 その時、この名前は具体的で分かりやすいと言えるでしょうか? もっと具体的な名前にすると、CanListenOnPortとした方が、メソッドの動作をそのまま表すことができ、 他者にも分かりやすく伝わります。

接尾辞や接頭辞を使って情報を追加する

時間はバイト数のように計測できるものであれば、変数名に単位を入れるのも良いです。 例えば、秒を返すのかミリ秒を返すのかが分かりにくい場合は、変数に_msを追加すれば明確になります。

名前の長さを決める

良い名前を選ぶときには、長い名前を避けて簡潔なものをと思いがちです。 長い名前を避けると1つの単語だけの名前になってしまいます。 変数の使い方によって違ってきますが、以下を参考にするとよいでしょう。

  • スコープが小さければ短い名前でもいい
  • 長い名前を入力するのは問題ではない
  • 頭文字と省略形
    BackEndManagerBEManagerにすると他の人全員に伝わるでしょうか?理解できるなら問題はありませんが、全員に伝わるか分からないような省略の仕方はやめた方がいいです。 しかし、evaluationをeval、documentをdoc、stringをstrのように省略するのは理解ができるので問題ありません。

  • 不要な単語を投げ捨てる
    名前に含まれる単語を削除しても情報が全く損なわれないこともあります。 例えば、ConvertToStringToStringにしたり、DoServeLoopServeLoopに変えても明確さは変わりません。

名前のフォーマットで情報を伝える

アンダースコア・ダッシュ・大文字を使って、名前に情報を詰め込むこともできます。 クラス名はキャメルケース、変数名はアンダースコアで単語を区切るなどの決まりを作っておけば、 文字列を見た時点で何を表しているのかが明確になります。

制御フローを読みやすくする

コードの制御フローを読みやすくするためにできることはいくつかあります。

  • 比較を書くときには、変化する値を左に、より安定した値を右に配置する
  • if/else文のブロックは適切に並び替える
     一般的には、肯定系、単純・目立つものを先に処理する。
  • 深いネストを避ける
     複雑な処理を書いていると知らない間にネストが深くなってしまうことがあります。
     ネストが深くなってしまった場合は、別の処理でどうにかできないかなど、
     一歩下がって全体を見るようにするのがいいかもしれません。

おわりに

初めてこの本を読んだ時は、まぁできるでしょうと特に引っかかることもなく読んでいました。
しかしコードを読み書きする機会が増えて読み直したら、こうやるのがいいのかと思うところが出てきてなるほどと思える部分が結構見つかるのです。
自分だけしか見ないコードならまだしも、他の人も見るコードは見やすさや分かりやすさを重視し、 少し分かりづらいロジックになってしまったのなら、せめて変数やコメントなどで分かりやすく伝わるようにしていくことが 大切です。

迷ったときにこの本を読み直してみると、自分のコードのどこに改善点があるのか見つかると思います。
定期的に読んで自分のコードを確かめてみるのもいいかもしれません。 自分もまだまだなので、改善していこうと思います。

参考

Copyright © RAKUS Co., Ltd. All rights reserved.