読みやすいソースコードを書くには - プログラマyasuhoの隠れ家

コードを読みやすくするためには相手が読む時のことを考えるという、思いやりの気持ちが大切なのだと思います。プログラムはそれが使われている間は常に変更されていきます。機能追加や変更がしやすく、バグの見つけやすいプログラムにするには、可読性を上げておくことが一番ではないでしょうか。

前々回および前回と、ソースコードを読む方法について書きました。

今回はソースコードを書く立場に立って、どのようにすれば読みやすいコードを書くことが出来るのか、考えてみたいと思います。

そもそも読みやすいコードというのは何でしょうか。読みやすいというのは、言い換えると「理解しやすい」ということですよね。構造がシンプルで、相手が見た時に構成や意味が理解しやすいものが読みやすいコードであると思います。

さて、前回コードを読む時のポイントを書きました。

これはコードを読む上での気をつけるべきポイントですが、逆にこれらの作業が少なくてすむ場合は、コードを読む時間と労力が減るはずです。

この考え方を元に、読みやすいコードの書き方を自分なりにまとめてみました。間違いや足りない部分などありましたら、指摘していただけると嬉しいです。

ソースツリーにおけるファイルやディレクトリの構成は、体系的に、構造や内容が見て分かりやすいようにしましょう。

コードはいくつかのディレクトリと複数のファイルから構成されることが多いです。機能単位で関数やメソッドをファイルに集め、それらファイルをさらに機能単位でディレクトリに整理することで、構造は理解しやすくなります。

ディレクトリ名はもちろん、ファイル名もなるべく機能を表す名前にしましょう。（私もよくやるのですが）subr.cやmisc.cppなどとせず、出来る限り意味のある分類にしましょう。

コードには、出来るだけ機能概要を表すコメントを入れましょう。

こういったものを関数やメソッドの先頭に書くと可読性が上がります。利用する上での注意点などもあると、実際に使う場合にも役立つでしょう。

ただ、あまりにも細かく書きすぎると、コード修正の時にコメントは変更されない場合が多いので、実際の内容とかけ離れていってしまいます。概要程度にしておくのが無難です。

コードの行数が多くなってきたら、機能を見直したり分割して可読性を上げましょう。

コードを書いていくと、どうしても長くなりがちです。一つの関数やメソッドや長くなってきたら、機能単位に分割したりコメントをはさむなりして、見通しをよくします。一つのファイル内での関数の数が増えてきたのであれば、ファイルを分けられないかどうか考えましょう。

コードの書き方には一定のルールを設けると、読みやすくなります。

企業やプロジェクトチームのコードではコーディングのルールが設けられているところが多いですね。一定のルールに基づいたコードは見やすさだけではなく、プログラム全体を一定の品質に保つ効果があります。

あまりよいルールではなくて、全部書き直したい衝動にかられることもありますよね。実際に書き直すかどうかはともかく、最終的には一定の基準で書かれた状態にしましょう。

プログラム上の名前は、見ただけで機能が推測できるようにしましょう。

コードにおける名前はとても重要です。長さの制限がない限り、意味のあるものにしましょう。妙な短縮形はなるべく避けた方が無難です。APIの返却値でよく使われる｢0以外はOK、0はエラー｣なども、SUCCESSやFAILUREなどのマクロにすると、分かりやすさが上がります。

プライベートやローカルに使われるものはそれほどこだわる必要はないですが、一つの変数を多様な目的で使うことは出来るだけ行わないようにしましょう。後でバグの原因となりやすいです。

いろいろ書いてきましたが、コードを読みやすくするためには相手が読む時のことを考えるという、思いやりの気持ちが大切なのだと思います。

これらは他の人がコードを見る助けになるだけでなく、何より自分の役に立ちます。半年以上経過した自分のコードを見てみて下さい。だいぶ忘れているでしょう。

プログラムはそれが使われている間は常に変更されていきます。機能追加や変更がしやすく、バグの見つけやすいプログラムにするには、可読性を上げておくことが一番ではないでしょうか。

自分で書いておきながら、私自身これらを守ってないことは多いです。読みやすいコードを書くことは簡単なようでなかなか難しいですが、プログラマにとって最も大切な技術だと考えていますので、これからも精進したいと思います。