1ヶ月後でも読めるソースコードの書き方

Program

あなたはコードを書くときに何を重視して書きますか？実行時の速度だったり、拡張のしやすさといったところですか？
今回は読みやすいコード(=readable code)についてです。
私が考える読みやすいコードとは以下のようなコードです。

  • 関数(メソッド)名が適切に付いている
  • コーディングスタイルが一貫している
  • コメントが少ない

では、ひとつずつ例を挙げていきます。

関数(メソッド)名が適切に付いている

check_member()は特定のユーザーがメンバーかどうか判定する関数とします。

if (check_member(user)) {
    ......
}

上記のcheck_member()はif文の中で使用していることからbooleanが返ってくるだろうと予想できますが・・・駄目っ！この名前では、どのような時にtrueが返ってくるのかは関数の中身を見ないと分かりません。このように何かを判定するものには以下のようにisやhasを接頭辞として付けるべきです。

if (is_member(user)) {
    ......
}

このような名前を付ければ、中身を見なくてもuserがmemberである場合にtrueが返ってくると分かります。コードを読む目的がこのチェック関数ではない場合、中身を確認しなくてもよくなった分だけ次々と読み進められます。

コーディングスタイルが一貫している

既存のコードを修正または追加する場合などに気をつけて欲しいことです。
対象のコードがどんなに気に食わないカッコの書き方をしていようが、インデントがタブ(またはスペース)じゃなかろうが、命名にアンダースコアを使いたくなかろうが、既に書かれてあるコードにスタイルを合わせてください。あなたがどんなに優れたコーディングスタイルで書いたところで、全体で一貫しているコーディングスタイルを崩すことはコードを読みにくくするだけです。
どのぐらい読みにくいかというと、ほのぼの物語だと思ったら3話で突然魔法少女の頭が食べられたり全く救いの無い設定だったアニメの展開ぐらい読みにくいです。

for (int i = 0; i < n; i++) {
    for(int j=0;j<m;j++)
    {
        ......
    }
}

int hoge(int x, int y) {
    ......
}

int
hoge(int x, int y)
{
    ......
}

上記の例だけではそれほど読みにくく感じないかもしれないですが、読むコードの量が増えれば増えるほど読みにくくなります。
色々なスタイルが混じったコードは特定の意味の文や式の記述パターンが増えるので、読む上での判定パターンも増えます。結果として読むのが遅く(=読みにくく)なります。if-elseをたくさん連ねるのは遅いのと同じです。

コメントが少ない

これには賛否両論あるかと思います。一概には言えませんが、私はコメントが少ないほうが読みやすいと思います。例えば

if (check_member(user)) { // userがmemberならhoge()を実行
    hoge();
}

int has_car = true; // 車を持っていればtrue

というコードの場合、check_member()を前述のis_member()にすればコードがそのまま意味を表すようになるので、最初のコメントは要らなくなります。
次のコメントも要りません。変数の名前を適切に付けているため、コードそのものがコメントの役割も果たしているためです。コードを見れば(≠読む)分かることをコメントに書くのは冗長で無駄無駄無駄無駄です。
また

int flag;
......
// 1: mode A
// 2: mode B
// 3: secret mode
flag = 1;

のようなコメントであれば、まず1、2、3の定数に名前を付ければコメントなしで意味が分かるようになります。

const int MODE_A = 1;
const int MODE_B = 2;
const int SECRET_MODE = 3;

flag = MODE_A;

コメントがなくても可読性は落ちていません。
名前を適切に付ければコメントはかなり減らせると思います。コメントというものは得てしてほとんど(あるいはまったく)メンテされません。メンテされないコメントほどアテにならないものはありません。いつでも動いているコードの方が正しいので「コメントがアテにならないならコードをコメントにすればいいじゃない」というわけです。
逆にコメントを付けるべきところは、カリカリにチューニングしていて一見してなにをしているのか分からないコードや、理由があってわざと効率の悪い方法や無駄なことをしているところなどです。後者などは後々リファクタリングの名のもとに削除されかねませんので、コメントを付ける意味があります。

読みやすいコードまとめ

名前重要。名前重要。大事なことなので2回書きました。一貫したコーディングスタイルを前提に、名前を適切に付けてコード自体をコメントにするように心がける。それでも分かりにくいところはコメントを付ける。
それではよいコードリーディングライフを！