こんにちは。2019年度、新卒として入社した桂川と申します。今後、このTECHSCORE BLOGでも、何度か記事を書くことがあるかと思います。どうぞ、よろしくお願いいたします。
本記事では、読みやすいコード（ソースコード）を書く方法について紹介します。新人ソフトウェアエンジニアである私が、コードを書くとき、特に心得ておくことが望ましい内容だと考えたためです。プログラミング初学者の方には、「コードを書くときの指針の把握」、プログラミング熟練者の方には、「コードを書くときの指針の再確認」や「新人が陥る傾向のあるミスの把握」を目的として読んでいただけると幸いです。
読みやすいコードとは
はじめに、本記事の題名にもなっている読みやすいコードについて説明します。以下、Javaで記述された同じ振る舞いをする２つのコードを示します。どちらが読みやすいと思いますか？
コードA
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
public class Main { public static void main (String[] args) { int a = 10; int b = 10; int c = 10; int d = hoge(a, b, c); System.out.println(d); } private static int hoge(int X, int Y, int Z) { int a = X * Y * Z; return a; } } |
コードB
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
public class Main { public static void main (String[] args) { int length = 10; int width = 10; int heigth = 10; int cuboidVolume = getCuboidVolume(length, width, height); System.out.println(cuboidVolume); } private static int getCuboidVolume(int length, int width, int height) { int cylinderVolume = length * width * height; return cylinderVolume; } } |
記述量が少ないという理由でAを選択する人もいるかもしれませんが、私はBを選択します。理由は以下の点で、内容が理解がしやすいのはBだと判断したからです。
- 名前から関数の振る舞いが理解しやすい
- 名前から変数の意味が理解しやすい
以上でも示したとおり、私は記述内容が理解がしやすいという点で、Bを読みやすいコードだと判断しました。コーディングについて紹介している書籍「リーダブルコード」の著者であるDustin Boswell氏、Trevor Foucher氏もその著作の中で以下のように述べており、つまりは、一般的に読みやすいコードとは内容が理解しやすいものだと考えられます。
本書の目的は読みやすいコードを書くことである。その中心となるのは、コードは理解しやすくなければいけないという考えだ。具体的に言えば、誰かが君のコードを読んで理解する時間を最短にするということだ。
引用元：Dustin Boswell、Trevor Foucher 著、角 征典 訳（2012）『リーダブルコード――より良いコードを書くためのシンプルで実践的なテクニック』オライリージャパン
そして、前述した理解しやすいコードには、以下のような利点があります。
- プロジェクトで開発する場合、引き継ぎがしやすい
（特に、新たに加入したメンバーも理解がしやすい） - 不具合の修正がしやすい
- 汎用的である
以上より、理解しやすさを実現するために、読みやすいコードを記述することが望ましいと考えられます。
読みやすいコードを書く方法
本記事の目的は、読みやすいコードを書く方法の紹介とその促進です。中でも、特に、新人ソフトウェアエンジニアとして、いち早く役に立つもののいくつかについて紹介します。
（※本記事では、さまざまな参考文献に基づき読みやすいコードの書き方を紹介します。しかし、あくまで諸説あるうちの一説です。利用言語、環境、方針によって異なる場合があります。あくまで参考として読んでください。）
１．情報量の多い名前をつける
関数、変数は名前から代入する値の意味を理解できることが望ましいです。したがって、関数や変数は情報量の多い名前をつけましょう。
以下、意味の理解ができる名前をつけるための要点と例を示します。
- 値を意味する名前をつける
- 具体的な名前をつける
例：変数名は修飾語＋名詞、関数名は動詞＋目的語 - 略称の使用を避けた名前をつける
| 要点 | 良い例 | 悪い例 |
|---|---|---|
| 値を意味する名前 |
|
|
| 具体的な名前 |
|
|
| 略称の使用を避けた名前 |
|
|
変数、関数の名前は、上記のようなものが望ましいです。しかし、経験や知見の少ないプログラミング初学者にとって難しいかと思われます。以下のようなウェブサイトを活用することをお勧めします。
２．誤解のない名前をつける
関数や変数の名前は、意味や目的の誤解がないような状態が望ましいです。なぜなら、適切に名前をつけないと、読者によって解釈が異なり、誤解が生じる場合があるためです。したがって、関数や変数は誤解のない名前をつけましょう。
以下、誤解のない名前をつけるための要点と例を示します。
- 状態を意味するbool型変数はis、has、canといった動詞や助動詞から始める
- 範囲指定に用いる変数の意味を明確にする
| 要点 | 良い例 | 悪い例 |
|---|---|---|
| 状態を意味するbool型変数 |
|
|
| 範囲指定に使用する変数 |
|
|
例えば、状態を意味するbool型変数としてemptyを使用した場合、値が空（empty）かどうか、読者によって解釈が異なる場合があります。これをisEmptyとすることで、解釈が一意になり、誤解を防止できます。
３．一貫性があるコードを書く
コード全体を通して、一貫性があることが望ましいです。一貫性があるコードを実現するために、コーディング規約が存在します。コーディング規約とは、企業やオープンソースコミュニティ、あるいは特定のプロダクトごとに定められた、コードを書くときの統一的なガイドラインのことです。したがって、コーディング規約に基づいて一貫性があるコードを書きましょう。
以下にコーディング規約として存在しうる例を示します。
- 改行の位置やインデント、コメントの位置を規則正しくする
- 関連するコードをまとめる
- 類似コードは類似の組み立てにする
- 関数、変数の命名規則を統一する
また、関数、変数の命名規則には以下のようなものがあります。
| 関数、変数の命名規則 | 記述例 |
|---|---|
| パスカルケース （アッパーキャメルケース）
|
|
| キャメルケース （ローワーキャメルケース）
|
|
スネークケース
|
|
ケバブケース
|
|
例えば、一般的にJavaのコーディングでは、クラスの名前はパスカルケース、メソッド（関数）、フィールド（変数）の名前はキャメルケースが推奨されています。
４．価値のあるコメントを書く
コメントを書くことでコードの内容を補足できます。しかし、コードだけを読んで内容の理解ができる場合は、コメントを減らすことが望ましいです。したがって、安易にコメントを書かず、変数や関数は適切に名づけましょう。その上で、必要な価値のあるコメントを書きましょう。
以下に、不要なコメントを含むコード例を示します。
|
1 2 3 |
// String型の変数tはタイトルを意味する・・・1 // tに固定文字列を代入する・・・2 String t = "読みやすいコードを新人が書く方法"; |
上記のコード例は２点の改善ができます。
- 変数名に意味を含ませることで、コメントによる補足が不要になる
- コードを読むだけで理解できる処理について、コメントによる補足が不要になる
以下に改善後の例を示します。コメントによる補足もありませんが、これだけで内容の理解ができるコードです。
|
1 |
String title = "読みやすいコードを新人が書く方法"; |
また、価値のあるコメントの例として定数の補足があります。その定数が、なぜその値として定義されているのかを説明する必要があるためです。
以下に価値のあるコメント例として、定数の定義を示します。
|
1 2 3 |
static final int MAXIMUM_NAME_LENGTH = 30; // 許可されている名前の最大文字数 static final float CONSUMPTION_TAX_RATE = 0.08; // 消費税率（2019年9月2日現在） static final String TITLE = "TECHSCORE BLOG"; // 画面のタイトル |
５．マジックナンバーの使用を回避する
マジックナンバーとは、数値そのものの意味以外を含んでいない具体的な数値のことです。以下の理由で、マジックナンバーを利用すること（ハードコーディング）が望ましくない場合があります。
- 数値の意味が理解し難く、コードの難読化を引き起こす
- 数値を変更する場合、関係がある複数の箇所の変更が必要になり、バグの誘発の原因となる
具体的に、マジックナンバーを使用してしまっている例を紹介します。以下、利用者からの入力（名前）を受け取り、その文字数の長さが30未満か否かを判定するコードです。
|
1 2 3 4 5 6 7 8 9 10 |
public class Main { public static void main(String[] names) { for (String name : names) { if (name.length() <= 30) { // この30という数値がマジックナンバー System.out.println("名前チェックOK！"); } else { System.out.println("名前チェックNG！名前が長すぎます！"); } } } |
上記コードにおいて、最大文字数を意味する30という数字がマジックナンバーです。一見、問題がないように見られますが、この30という数字が何を意味するのかが分かりにくいです。この問題を解決する方法として、あらかじめ定数を定義しておくのが一般的です。以下に例を示します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
public class Main { private static final int MAXIMUM_NAME_LENGTH = 30; // 名前の最大文字数 public static void main(String[] names) { for (String name : names) { if (name.length() <= MAXIMUM_NAME_LENGTH) { System.out.println("名前チェックOK！"); } else { System.out.println("名前チェックNG！名前が長すぎます！"); } } } } |
上記コードでは、あらかじめ、名前の最大文字数を意味するMAXIMUM_NAME_LENGTHを30と定義しています。この場合、プログラムの内容も理解しやすいです。そして、もしこの最大文字数を変更する場合でも、難なく対応できます。
まとめ
本記事では、読みやすいコードを書く方法、特に新人にとっていち早く役に立つものについて紹介しました。読みやすいコードを書く方法について調査するにつれて、奥が深いものだと感じました。読みやすいコードを書いたとはいえ、プログラムの振る舞いが変わることはないです。しかし、会社、プロジェクトなど複数人で作業をする場合は、特に重要なことだと思います。自分自身、今後も調査し、学び、書くコードが読みやすいコードになるよう、精進していこうと思います。
最後まで読んでいただき、ありがとうございました。
