【リーダブルコード】よいプログラムを目指してみる

こんにちは、Яeiです。

今回は現役エンジニアの私が、リーダブルコードについて調べてみましたので、その考え方をシェアさせて頂きます。

現場では度々「コード解析するのに無駄な時間がかかる」というものが散見されます。

私自身、そういったコードを書いてしまっていないか今一度新ためるべく、リーダブルコードの考え方を調査致しました。

結論

今回、以下の書籍を参考に致しました。

初版が2012年発売の名作となっておりまして2019年に最新版が出ております。

こちらの書籍は今も廃れない名作となっておりますので、プログラミングに携わる人は是非一度は読んでみて下さい。

リンク

コードは他の人が最短時間で理解できるように書かなければならない

この記載は書籍の一番最初の方に記載されていることなのですが、リーダブルコードの全てをこの一行が表しているのではないでしょうか。

こちらの書籍「リーダブルコード」でも、ネット検索などで出てくるリーダブルに対する見解でもこれに尽きます。

ただし、これを達成するためにあれやこれやと細かいテクニックや議論が繰り広げられているのです。

今回はリーダブルコードを達成するための手法ではなく考え方について説明致します。

他の人が見て理解できるコード

大切な事なのでもう一度記載しておきますが、リーダブルコード（読みやすいコード）とは以下のようなコードとなります。

他の人が最短時間で理解できるようなコード

書籍ではこれを達成するために以下のような手法を教えてくれます。

・ネーミング

・コメントの付け方

・ロジックの最適化

ネーミングやコメントの付け方については後述致しますが、ロジックの最適化については細かい話になりますので書籍を読んでみて下さい。

ここで少し議論したい点は「他の人が最短時間で理解できるようなコード」の「他の人」をどのレベルで考えるかによって納得の是非が変わってくるという点です。

例えば、書籍では以下のようなコメントは無駄だから辞めようと述べております。

// Accountクラスの定義
Class Account {
    public:
        // コンストラクタ
        Account();

        // profitに新しい値を設定する
        void SetProfit(double profit);

        // このAccountからprofitを返す
        double GetProfit();
};

これに関しては疑いの余地もなく書籍のみならずネットの民も賛同することでしょう。

・・・本当に？

この例に関しては私もコメント不要派なのですが、少しだけ考えてみましょう。

例えば新入社員の観点からもう一度上記のコードを見てみましょう。

すると、コメントはあった方が分かりやすいですし、逆にコメントを消した方が良いという意見の方が謎に感じる事でしょう。

もしかしたら、英語に不慣れな日本人の感覚としてはコードを追う際に、実コードではなくコメントを追っていく人も少なくないのではないでしょうか。

そうすると、新入社員に関わらず、多くの入門者にとってコメントのないコードはさながら英語の読解問題の如く構えてしまうコードになるかもしれません。

例えそれが上記のように技術的に難しくないコードであったとしても。

そのため、英語に慣れている人やプログラミングに慣れている人にとっては上記のようなコメントは不要ですが、それ以外の人にとってはコメントはあっても良い気がします。

では、それ以外の人はどの程度いるのか、というのが論点となりそうです。

残念ながらどちらがマイノリティかデータを取ったわけではないので一概には言えませんが、

プログラミングする際は「誰にとって分かりやすく書くか」を決めてから書くようにしましょう。

例えば、現行システムのメンテナンスの場合は、オリジナリティを入れるよりかは現行に合わせておいた方がメンテナンスはしやすいでしょう。

（なぜならば、メンテナンスした１コードだけスタイリッシュに書かれていると既存メンバーは面食らってしまうことでしょう）

新規プロジェクトであれば、プロジェクトメンバー同士で足並みをそろえれば良いでしょう。

ネーミングについて

さて、先ほどは「誰にとってリーダブルか」について話をしました。

しかし、一般的に誰にとってもリーダブルな書き方として「ネーミングの考え方」があります。

変数や関数名は用途をハッキリさせる

抽象的な名称は確かに使い回しできて便利ではあります。

しかし、多くの場合、その変数に何が入っているのか分かりませんし、それ故にバグの原因ともなり得ます。

そのため、

ネーミングの鉄則は「具体的な名前を付ける」こと。

例えば入力したURLデータに対して、URLエンコーディングした値を入れる変数の場合は「data_urlenc」のように。

このとき、略称についてはプロジェクト固有の略記ではなく一般的に用いられる略記のみ利用するように心がけると良いとのことです。

（これは新規プロジェクト参画者を想定してのこと）

ちなみにですが、昔のコードではハンガリアン記法が採用されているケースが多くあるようですが、こちらはメンテナンス性の悪さから非推奨だそうです。

参考
なぜ命名規則が必要なのかDeep Rain

コメントについて

こちらも書籍の中で目的を明記しております。

コメントは、書き手の意図を読み手に知らせる際に記載する

先の例で以下のコードにコメントは必要か、不要かという話を少ししましたが、この意識付けである程度解消されるでしょう。

// Accountクラスの定義
Class Account {
    public:
        // コンストラクタ
        Account();

        // profitに新しい値を設定する
        void SetProfit(double profit);

        // このAccountからprofitを返す
        double GetProfit();
};

例えば、新人研修で扱う題材とか、入門書レベルで扱う際はコメントが書かれている方が良いでしょう。

一方で、ある程度熟練された現場レベルであればコメント不要でしょう。

どこまで丁寧に（あるいはお節介に）コメントを残すかはこの基準で考えると良さそうです。

また、書籍の中では「書き手の意図を積極的に残す」ことをオススメしております。

回りくどい処理になってしまっている場合に「なぜ回りくどい書き方をあえて行っているのか」など、コメントを残すのです。

そうすれば、後世の民が「この理由ならこの方法で簡単に解決できるよ☆」みたいにメンテナンスも容易になります。

このように、コメントは

後世の民（数ヶ月後の自分）への申し送り事項

と思って付けると良さそうです。