キレイなコードを書くための基本 － 事例で学ぶクリーンコード
はじめに
分析屋の伊藤です。
開発の現場にいると、自分が一からコードを書くよりも、既存のコードを改修する機会の方が多いように思います。それが過去に自分が書いたコードであればまだ意図を理解しやすいのですが、他人が書いたコードを解読して改修するとなると、ものによっては「？？？」ってなることも多々あるので、いかにコードの読みやすさが重要かということを痛感します。
そこで今回は、少しでもコードをキレイに書くために心掛けたいこと、いわゆるクリーンコードの基本的なテクニックについてまとめました。私の過去の失敗談を交えながら、すぐに実践できるポイントをいくつかご紹介していきます。
クリーンコードとは
クリーンコード（Clean Code）とは、初めてそのコードを見た人が容易に理解、変更ができるコードを指します。
原則としては、
他人が読みやすい
新規機能を追加しやすい
修正によるバグが混入しづらい
などがあります。
クリーンコードはなぜ重要なのか？
プログラム開発の指標の1つとして、「保守性」というものがあります。これはコードの可読性や拡張性の高さを示すもので、変更や修正のしやすさに直結します。
プログラムは一度完成したら終わりではなく、状況の変化に応じて定期的にアップデートされるのが一般的です。その際に、保守性が高いコードであれば、意図を解読しやすく、変更や修正にかかる時間を短縮できるというメリットがあります。
一方で、保守性が低いコードは、仕様変更のたびに解読に時間と労力がかかり、場合によっては一からコードを作り直さなければならないなんてこともあります。自分が書いたコードですら「何でこんな書き方したんだっけ？？」となることもありますし、そんなコードであれば他の開発者にとってはなおさら理解しづらいということになります。
そのため、日ごろからコードをキレイに書くことを心掛けておくことが重要なのです。
コーディング例
それでは、具体的にはどんなものが望ましいとされるのかを悪い例と良い例を示しながら解説していきます。
1 . 変数名のネーミング
コードを書くにあたって、ほとんどの場合は変数を用いることになりますが、そのネーミング次第で理解しやすさが大きく変わります。
以下は、消費税込みの金額を計算するコードをPythonで記述した例です。
悪い例
a=1000
b=0.1
c=a+(a*b)
print(c)上記コードの悪い理由は、以下のようなものがあります。
・a、b、cという変数名が何を表しているのかがわかりにくい
・コードを読んだだけでは何を計算してるのかわかりにくい
・変数に値を代入する際にスペースを空けていないため、見づらい
・変数名にスネークケース（※）が用いられていない
良い例
price = 1000
tax_rate = 0.1
total_price = price + (price * tax_rate)
print(total_price)上述した悪い理由を改善したところ、このようなコードになりました。
こちらは、以下のような理由から、良い例だといえるかと思います。
変数名が何を表しているのかが明確なため、何の計算をしているのかがわかりやすい
変数に値を代入する際にスペースを用いることでコードが見やすい
変数名にスネークケース（※）が用いられている
スネークケース（snake_case）とは？
単語間の区切りにアンダースコア（_）を使い、全て小文字で記述する命名規則を指します。snake_caseという表記が、蛇が這っているように見えることから、このように呼ばれています。Pythonでは、変数名、関数名はスネークケースを用いて記述することが推奨されています。
上記はPythonの例を紹介しましたが、言語や識別子の種類（変数名、関数名、クラス名など）によって、推奨される命名規則は異なります。
例えば、JavaScriptではキャメルケース（camelCase）という単語の最初の文字を小文字にし、次の単語の最初の文字を大文字にするというスタイルが一般的です。
こちらの記事はよく使う言語の命名規則が一覧化されていますので、詳しく知りたい方はご覧ください。
2. 関数呼び出し時のパラメータ
先ほど、変数に値を代入する際にはスペースを入れるべきと述べました。それに慣れてくると、=を使う場合は前後にスペースを空けるものだと認識し、無意識にスペースキーを入力してしまうこともあります。
但し、ここで注意すべき点があります。=を使う場面でも、スペースを入れるべきでないコードがあります。それは関数呼び出し時にパラメータを指定する場合です。
以下は、商品の割引価格を計算する関数の例です。
悪い例
def calculate_discounted_price( base_price, discount_rate = 0.1 ):
return base_price * (1 - discount_rate)その理由としては、
・, の前後にスペースを入れることで、引数がどこで区切られているのかが直感的にわかりにくくなる
・デフォルト引数の=の前後にスペースを入れると、引数のデフォルト値の指定と通常の代入文が区別しにくくなる
というものがあります。
「え、そうかな？」と思われた方もいるかもしれませんので、良い例のほうで見ていきましょう。
良い例
def calculate_discounted_price(base_price, discount_rate=0.1):
return base_price * (1 - discount_rate)たしかに、こうして比較してみると、関数の引数部分とreturn文では違いがわかりやすくなり、明確に区別できるようになりますね。
以前の私は、どちらもスペースを空けていたのですが、コードレビューを受ける際にレビュアーの方に指摘されてそこで学びました。
PEP8というPythonのスタイルガイドでも、この形が推奨されているようです。
興味がある方は読んでみてください（英語ですが）。
3. コメントの使い方
クリーンコードを書く上で、コメントを残すことは重要ですが、使い方を誤るとかえって見づらいコードになってしまうので注意が必要です。
悪い例
# 商品情報を取得
product = get_product_info(product_id)
# ユーザー情報を取得
user = get_user_info(user_id)
# 配送先住所を確認
address = check_address(user) 処理1つ1つにコメントがされており、一見わかりやすくて良さそうに見えるかもしれませんが、区切りが目立ちすぎてコードの流れが途切れてしまい、かえって見づらいコードになっています。
良い例（コメントなし）
product = get_product_info(product_id)
user = get_user_info(user_id)
address = check_address(user)こちらの例ではコメントを排除し、コード自体の意味を変数名や関数名から読み取れるようにしています。短いコードの例なので、どちらでもさほど影響はないように感じるかもしれませんが、これが長いコードになると、コメントが多いことが冗長さを感じさせ、理解を妨げる原因にもなり得ます。
私はプログラミングを始めた当初、まさに悪い例のようなコードを書いていました。その理由としては、このようにすることで他の人が見てもそこで何の処理をしているのかがわかりやすくなり、それが丁寧さに繋がると思っていたからです。
しかし、それは自己満足に過ぎなかったということに後から気づきました。そもそも変数名や関数名などは、何を表しているのかがわかるようなネーミングにすることが原則となっており、それらから読み解くべきものであるため、こういった単純なコメントは不要なのです。
それでは、どんな場合にコメントが必要なのか？それは、コードだけでは意図がわかりにくい場合です。
「なぜこの処理が必要なのか？」という背景がコードから読み取れないものに関しては、コメントをつけるべきとされています。
例）
def get_shiping_cost(weight):
# 物流会社の規定により、20kgを超える荷物は特別配送扱いとなり、一律5,000円の送料がかかる
if weight > 20:
return 5000
return 3000こちらはコードの内容自体は簡単なので、コメントがなくても重さが20kgを超える場合は5,000が、それ以下であれば3,000という値が得られる（さらに、関数名にshiping_costとあるのでその値は送料を表す）というのは読み取れるのですが、コメントをつけることにより「なぜ20kgで区切るのか？」というビジネス上のルールが明確になり、ただの単純な計算ではなく物流会社の特別ルールであることがわかるようになります。
おわりに
今回はクリーンコードの事例について、いくつか簡単なものをご紹介しました。一見シンプルに思えるルールでも、実際に意識して書こうとすると意外と奥が深く、1つの記事だけで全てをまとめるのは難しいので、今回は簡単なものをピックアップしました。ここでは書ききれなかったこともありますので、そのへんはまた別の機会にでもご紹介できればと思います。
コーディングのルールは、現場やプロジェクトごとに異なることもありますが、「他の人が読みやすく、保守しやすいコードを書く」という本質的な目的は変わりません。
私自身も、より良いコードを書くことを心掛けていきたいと思います。
今回の記事が少しでも参考になれば幸いです。
ここまでお読みいただき、ありがとうございました！
この記事が少しでも参考になりましたら「スキ」を押していただけると幸いです！
株式会社分析屋について
弊社が作成を行いました分析レポートを、鎌倉市観光協会様HPに掲載いただきました。
ホームページはこちら。
noteでの会社紹介記事はこちら。
【データ分析で日本を豊かに】
分析屋はシステム分野・ライフサイエンス分野・マーケティング分野の知見を生かし、多種多様な分野の企業様のデータ分析のご支援をさせていただいております。 「あなたの問題解決をする」をモットーに、お客様の抱える課題にあわせた解析・分析手法を用いて、問題解決へのお手伝いをいたします！
【マーケティング】
マーケティング戦略上の目的に向けて、各種のデータ統合及び加工ならびにPDCAサイクル運用全般を支援や高度なデータ分析技術により複雑な課題解決に向けての分析サービスを提供いたします。
【システム】
アプリケーション開発やデータベース構築、WEBサイト構築、運用保守業務などお客様の問題やご要望に沿ってご支援いたします。
【ライフサイエンス】
機械学習や各種アルゴリズムなどの解析アルゴリズム開発サービスを提供いたします。過去には医療系のバイタルデータを扱った解析が主でしたが、今後はそれらで培った経験・技術を工業など他の分野の企業様の問題解決にも役立てていく方針です。
【SES】
SESサービスも行っております。