はじめに

私はエンジニアを目指して勉強している学生です。いろいろコーディングの本を参考に、理論と技術磨きを頑張っています。最近、コードの可読性について考えていることをまとめて、学内のDiscordサーバに流してみました。ただそれを学内に流すだけではもったいないと思い、可読性について疑問を持つ方がいると信じて公開してみようと思います。
あくまで私が勉強と実践の中で感じたこと、思ったことをまとめた書き物です。全くの実務未経験の考えですので、「ここおかしいんだが？」「そんなわけない」等ありましたら、ぜひ温かい目での指摘をお願いします。

なお、本文のコード例はUnity/C#です。

対象者

プログラミング初学者
可読性をもう少し掘り下げてみたい方

可読性とは何だろうか？

可読性とは何でしょうか？
「コードが読みやすいこと」という説明はすぐに思いつくはずですが「もうちょっと具体的に...」と言われたとき、どう表現しましょうか？
「コードのインデントをキレイにして、改行して...」と具体的な手段での表現になるかと思いますが、どうも表現しきれていない気がします。そこで、この記事で私なりに「可読性」について分類と定義をしてみようと思います。まず分類はこのようになると考えています。

「叫ぶ」可読性
「沈黙の」可読性
「言語の」可読性
「美しい」可読性
「良いにおいの」可読性

可読性と聞けば「見る」ことにフォーカスが当てられがちで、この分類に違和感を持たれるとは思いますが、コードは見るだけのものではありません。可読性は「五感を使って味わう」ものです。その理由をそれぞれの定義で見ていきましょう。

叫ぶ可読性

コードはうまく書くと叫ぶし、すぐに自分を語り始めます。しっかり聞こえてくるはずです。そして、健全なコードはそうあるべきです。その名前を見ただけで「これは何をするのか」が理解できる。これが叫ぶ可読性です。

例えば、変数の名前を省略してはいませんか。

public int Calc(int p, float tr) {
  int res = p + (int)(p * tr);
  return res;
}

これではコードが叫びません。つまり何をしているのかがわからないのです。省略によって、後述する叫ぶコメントが必要になってしまいます。

/// <summary>
/// 税込み価格を算出する
/// </summary>
/// <param name="p">価格</param>
/// <param name="tr">税率</param>
/// <returns>税込み価格</returns>
public int Calc(int p, float tr) {
  int res = p + (int)(p * tr);
  return res;
}

そこでこう書いてみましょう。

public int GetPriceIncludingTax(int price, float taxRate) {
  int total = price + (int)(price * taxRate);
  return total;
}

これでコードが叫ぶようになりました。
「私は税率計算の関数で、金額と税率を貰うと税込価格を返します」
全てのコメントが不必要だ、という訳ではありませんが、叫ぶコードを書けばそのコメントが無くても良い可読性は保証できます。

沈黙の可読性

叫ぶばかりではなく、逆に沈黙すべきところもあります。
コードはうまく書くと叫ぶはずです。そして気を利かせたプログラマはそれにコメントを付け加えます。コメントは何もしなくても叫ぶものです。それを叫んでいるコードに付け加えるとどうなるでしょうか。叫び声は二重になっています。これでは騒音トラブルになってしまいます。どちらかの口を封じなければなりませんが、「叫ぶ可読性」より、叫んでいるコードを書ければコメントは少なくて良いはずと言うことを知っています。ならばコードに叫ばせてコメントは黙らせればよいのです。これが沈黙の可読性です。あえて沈黙を守ることで可読性を得る。「雄弁は銀」と言うことです。
上記のコードも、名前を見れば「何をするのか」がわかります。GetPriceIncludingTax、「取得する、価格、含む、税」、引数は price, taxRate 「価格」「税率」、カタコトの日本語でさえ、「何をするのか」が理解で切るはずです。

しかし、時たま「コードが沈黙する」ことがあります。そういったときにはコードに代わってコメントが叫ばなければなりません。ここでは「雄弁が金」です。

/*
 * NOTE: アルゴリズムA が主流だが、より早いアルゴリズムBを実装
 * FIXME: 安定はしたがいまだ不安定 検証必須
 */

コメントが叫ぶときは、「なぜ」と「なぜそうでないか」を書くときだけです。コメントが叫ばなければならないときは、コードだけで決められない部分があるときに限られます。

//NOTE: 現状使用しているRDBMSに都合がよい

//NOTE: このアルゴリズムは難解だが早いので関数にカプセル化した

しかし、それ以外でコメントが叫んでいるときは「何か別の、もしくは全体が間違っている」時なのかもしれません。いったん全体を見渡してみる、というのも良いのではないでしょうか。

言語の可読性

われわれ日本人は日本語を話します。そしてほとんどの人がコメントを日本語で書きます。しかしプログラミング言語というものはほとんど英語です。すなわち我々はコメントとプログラミング言語の間で言語の差を持っています。
言語を読む時は、頭が切り替わります。ちょうどプログラミング言語でコンパイルするときにはその言語専用のコンパイラが必要になる具合です。もしコードを読む時、一行一文ごとに日本語と英語の切り替えをしていたらどうなるでしょうか。

//足し算をする
public int Add(int a, int b) {
    //結果用の変数を宣言、初期化
    int res = 0;
    //変数に引数を足し合わせて代入
    res = a + b;
    //結果を返却
    return res;
}

短時間での高速切り替えで頭の回路がショートしてしまうに違いありません。「叫ぶ可読性」と合わせてこう書いてみましょう。

public int Add(int lhs, int rhs) {
    int result = lhs + rhs;
    return result;
}

または、

/// <summary>
/// 単純な足し算
/// </summary>
public int Add(int lhs, int rhs) {
    int result = lhs + rhs;
    return result;
}

同じ言語なら同じ言語でまとめてあげる。こういった「言語の流れ」を意識することが、言語の可読性です。
また、コメントは「コードの語訳を書くものではない」と言うことも言語の可読性のうちです。その語訳は、いつ「誤訳」になるかわかりません。

美しい可読性

コードは芸術です。自分の考えを創作的に表現すること、まさにコーディングでしょう。

単純な話をしてみます。
あなたはある美術館を訪れました。入館してすぐ目に入った展示芸術品は、ボロボロ、汚い、作りが雑......。
どう思うでしょうか。
(「そういうアヴァンギャルドだ」「ヴィンテージだ」と言われてしまえばそこまでですが...。)

まさに同じことがコードでも起こりえます。美的センスの試されどころと言ったところでしょうか。

public class SomeClass : MonoBehaviour {
  private int someVar;
  private int anyVariable = 0;
  [SerializeField] AnyClass _any;

  void Start()
  {
    _any.Init();
  }

  private void Update() {
    _any.DoUpdate(someVar);
  }
}

命名規則がない、省略があったりなかったりする、バラバラ......。
さて、どう思いますか？。

良いにおいの可読性

コードにはにおいがあります。実際に嗅げるかといえば「人(と経験)による」が答えなのですが、発生原因は現実と同じメカニズムを持っています。
風通しの良い場所で干した洗濯物は太陽の良い香りがするが、それを適当に折り重ねておくとたちまち異臭が漂い始める。
これと全く同じです。
風が通るように処理の内容が明らかなコードに異臭はしない。これが良いにおいの可読性です。

しかし風が全く通らない入り組んだコードからは異臭が漂います。

if (wetLaundry) {
    if (!foldedLaundry) {
        if (laundry) {
            ...
        }
    }
}

一番下にある wetLaundry はもう最悪で、今すぐにでも悪臭が漂ってきます。少なくとも私はにおいを感じています。こういったコードを見かけたらすぐに洗濯物をハンガーにかけてあげましょう。これがリファクタリングです。それでももし悪臭が取れないようならもう一度洗濯、もしくは漂白剤でリセットしてあげましょう。これはリアーキテクチャです。

さいごに

可読性の分類と定義を見ていきました。このようにコードの可読性とは五感を使って味わい、改善していくものだと考えています。今一度自分のコードを見て、そのコードを五感で感じてみてください。その時から違う視点が起き、コーディングが変わるはずです。

結論

私はこのような思想で日々プログラミングをしています。こういったコードを日々書いていれば、制作で役に立つことも経験しました。「コード規約とか守っていられない」「何のためにやるのか」と思っている方には、それを考え直すきっかけになればなと思います。

参考

"リーダブルコード" - Dustin Boswell, Trevor Foucher 共著
"良いコード/悪いコードで学ぶ設計入門" - 仙塲大也著
"Clean Architecture" - Robert C. Martin 著
"リファクタリング第二版" - Martin Fowler 著
"達人プログラマー第二版" - David Thomas, Andrew Hunt 共著
経験 - 偉大な先輩、偉大なエンジニアより