リーダブルコード=他の人が最短時間で理解できるコード

PG基礎

1. はじめに

＜**リーダブルコード-より良いコードを書くためのシンプルで実践的なテクニック＞** 上記の書籍を読み、勉強になった点や共感した点をまとめます。

リーダブルコードの定義として、上記の書籍では 他の人が最短時間で理解できるコードと記載されています。ここでいう他の人というのは「6ヶ月後の自分」であるかもしれません。

2. リーダブルコード

2-1. 名前の付け方

自分は名前(変数名、関数名、クラス名等)を決めるときかなり悩むことがあります。。。最善の名前とは誤解されない名前となります。 誤解されない名前にするために、名前に情報を埋め込む必要があります。 (名前は短いコメントのようなもの、とよく耳にしますね。)

2-1-1. ページを外部から読み込み取得するメソッド

// ■ 悪い例
Page GetPage()

// ■ 良い例
Page LoadPage()

Getは頻繁に使いがちですが、意味が汎用的すぎます。メソッドの情報をイメージしやすい名前にするとよいです。

2-1-2. 名前から人を検索するメソッド

// ■ 悪い例
List<Person> GetByName(string name)

// ■ 良い例
List<Person> FindByName(string name)

同上。

2-1-3. ヒットしたインデックスのリストを返す際に使用する変数

// ■ 悪い例
List<int> result = new List<int>();

// ■ 良い例
List<int> matchedIndexes = new List<int>();

名前が思いつかないときなど、つい使ってしまいますが、resultは結果以外の何の意味ももちません。変数の値を表すような名前を付けることで、変数が使いまわしやすくなります。

2-1-4. ファイルのサイズをチェックするメソッド

// ■ 悪い例
bool isFileSizeOver(File file, int size)

// ■ 良い例
bool isFileSizeOver(File file, int size_kb)

名前からsizeの単位が読み取れず、不具合にもつながります。プレフィックス/サフィックスを付けることで、情報を付加できます。

2-1-5. 指定した文字列を含む要素を除外するメソッド

// ■ 悪い例
AllObjects.filter("year <= 2011")

// ■ 良い例
AllObjects.excludes("year <= 2011")

filterでは、「year <= 2011」のオブジェクトに絞るのか、「year <= 2011」のでないオブジェクトに絞るのか名前から判断することができません。

2-2. コメント

コメントは、プログラムにとって不可欠なもので、 コードの意味を読み手に理解してもらうことが重要になります。

2-2-1. 価値のないコメントはしない

// ■ 悪い例
// プロフィールを取得する
Profile prof = getProfile(name)

新しい情報を提供するわけでもなく、読み手がコードを理解しやすくなるわけでもありません。価値のないコメントとなるため、不要となります。 (こちらについては、賛否両論あるかもっ！！)

2-2-2. 自分の考えを記録する

// ■ 良い例
// 当データの場合、ハッシュテーブルよりもバイナリツリーの方が40％程度早い

コメントから情報を得ることができるので、下手に最適化しようとするなど無駄に時間を使う必要がなくります。

2-2-3. 欠陥についてのコメントを残す

// ■ 良い例
// TODO:
// 10000要素で5秒程度の時間がかかっているため
// もっと高速に処理できるように修正が必要

コードは絶えず進化する傾向にあるため、少なからず欠陥を生むことがあります。欠陥を文書化することを恥ずかしがらず、改善が必要なときは上記のようなコメントを残すことが大事です。

2-2-4. 代名詞を使わない

// ■ 悪い例
// データをキャッシュに入れる。ただし、先にそのサイズをチェックする

// ■ 良い例
// データをキャッシュに入れる。ただし、先にデータのサイズをチェックする

「その」が示しているのは、「データ」なのか「キャッシュ」なのか即座に判断できません。読み手がイラッとするポイントの一つです。

2-2-5. 関数の動作を正確に記述する

// ■ 悪い例
// このファイルに含まれる行数を返す
int CountLine(strig filePath) { 

// ■ 良い例
// このファイルに含まれる改行文字(¥n)を数える
int CountLine(strig filePath) {

悪い例では、以下のケースはどうなるのかが曖昧となります。　・""(空ファイル)は0行なのか1行なのか　・"hello"は0行なのか1行なのか　・"hello¥n"は1行なのか2行なのか　・"hello¥n world"は1行なのか2行なのか良い例のようなコメントに変更することで、コメントの量は変わらないのに、伝わる情報が格段に増えます。

2-2-6. 実例で補足する

// ■ 良い例
// 平成和暦日付文字列を解析してDateとして返却する。
// 例：
//   "平成1年2月3日" はOK
//   "H.1.2.3" はOK
//   "H.1.2月3日" はNG
Date parseHeiseiWareki(String dateExpression)

複雑な関数や、間違った使われ方をされそうな関数等は、実例を定義すると分かりやすくなります。

3. おわりに

リーダブルコードに関しては正解がないため、個人個人の考えがあるかと思います。また、自分との趣味が合わなくても、当然ですがコーディング規約に沿う前提にはなります。上記は一例ですが、コーディングの際、少しでも参考になりますと幸いです。