MENTAでは、プログラミングを学習中の方が多いと思います。
副業で案件受注を目指したり、転職してエンジニアを目指したりする人もいると思いますが、可読性の高いコードを書くことが評価ポイントになることもあるので、意識しておいていただきたいことです。

ここでは、これまでの私の経験等を基に「コードの可読性」について、書いてみたいと思います。

個人的意見も含まれているので、参考程度で読んでいただければと思います。

コードの可読性とは？

コードの可読性とは何でしょうか？
コードの読みやすさということですが、もう少し具体的に表現すると、プログラミング言語を用いてどんな処理を実行するコードが記述されているかの理解のしやすさと言えると思います。

次の3つがコードの可読性を左右する要素だと思います。

  • コードスタイル
  • ネーミング
  • コメント

コードスタイルは、インデントや空白の入れ方、括弧の位置などの見た目の様式のことです。
これに関しては、近年ではIDE（統合開発環境）の機能などを利用して、簡単にコードを整形（フォーマット）できるようになっているので、あまり問題にはならないと思います。
例えば、PHPではPSRという規約がありますが、IDEにPSR用のフォーマッター設定があらかじめ用意されていたりします。

ネーミングは変数名や関数名の命名のことです。
慣例としてある程度のルールが定められていたりしますが、あまり長くならずに分かりやすい名前を付けるのは簡単なことではありません。

コメントはプログラムについての説明を記述するものですが、最も個人差が出やすいところだと思います。

「ネーミング」と「コメント」について、もう少し詳しく説明したいと思います。

コードの可読性がなぜ大事か？

その前に、なぜコードの可読性は大事なのでしょうか？
それは、後からプログラムを修正したりすることがあるからです。

プログラムは一度書いて完成したらそれで終わりではありません。

テストも終了し、完成したと思っても、システム稼働後にバグが発覚することがあります。
そうすると、どこに原因があるか、コードを調べることになります。
当然、バグの原因となった箇所は修正も必要です。
システムが複雑化するにつれ、バグが多くなったり、解決するのが難しくなってきているということもあります。

リリース後に機能追加したり、仕様変更したりすることもあります。
この時は、変更の影響がどこに及ぶか、仕様書などのドキュメントを見ただけでは影響範囲が分からず、コードを調査することもあります。
実際に追加開発する際には、既存コードを修正する必要も出てきます。

そして、近年はITの普及が進展するにつれて、ビジネス環境の変化に応じて新しい要件に対応する必要性が高まる傾向が強くなりました。
機能追加・仕様変更の頻度が以前よりも多くなってきているのです。

また、昔とは開発スタイルも変わってきました。
昔は、上流工程でしっかり仕様を固めて、設計・実装・テストと進めていくウォーターフォール型の開発スタイルが一般的でした。
最近では、インクリメンタルに開発を進めていくスタイルが導入されることもあり、この場合には、プログラムをリファクタリングしてブラッシュアップしていくこともあります。

このように、さまざまな理由で、以前よりもコードの可読性は大事になってきています。

ネーミング

ネーミングの中でも、まず形式があります。
英単語をアンダースコアでつなぐ「スネークスタイル」、2つ目以降の英単語の先頭文字だけ大文字にしてつなげる「キャメルケース」、最初の英単語の先頭文字も大文字にする「パスカルケース」などがあります。

これらはプログラミング言語によって、多少扱いが違います。
変数名は数字で始まってはいけないなど、文法上許されていないルールがありますが、それに違反していなければ、このスタイルが理由でエラーになることはありません。
しかし、それぞれのプログラミング言語で慣例のようなものが決まっているので、それに従いましょう。

大雑把に言うと、変数名や関数名は「キャメルケース」、オブジェクト指向が導入されている言語のクラス名は「パスカルケース」が一般的です。
「スネークケース」は、以前はスクリプト系言語でよく使われていたと思いますが、最近はあまり使われなくなっているのではないでしょうか？（個人的見解です）
プログラミング言語ではないですが、「スネークケース」はデータベースのテーブルのカラム名でよく使われていると思います。

そして、問題になるのが、どんな英単語を使うかです。
ちなみに、英語が苦手だからという理由で、ローマ字を使う人がいたりしますが、これはNGです。

変数名や関数名には、どんな処理が行われるかイメージしやすい単語を使うべきです。
しかし、非常に長い単語を使ってしまうと、文が長くなってしまい、余計な改行が増えて、全体が読みづらくなるという弊害が出てきます。
また、勝手に単語を短縮形にする例もありますが、これは本人にしか理解できないような記述になりがちなので、できるだけ避けた方がよいと思います。
誰もがこの単語の短縮形だと分かる場合は例外的にOKだと思います。

慣れないうちは、変数名や関数名を何にすべきかで悩んだりすることもあると思います。
しかし、登録・更新・削除など、プログラムの処理は典型的なものが多いので、それらを一度覚えてしまえば、コーディングもスムーズに進みます。
命名ルールについてまとめたサイトなどがありますので、一度調べてみるとよいと思います。

ちなみに、変数名やクラス名は名詞にする、関数名は動詞で始めるなどの慣例があります。

コメント

コメントは処理内容を理解するために重要な情報です。
しかし、特にルールが決まっていない場合が多く、個人の判断に任されているケースが多いです。
適切なコメントを書くにはどうしたらいいでしょうか？

なお、メソッドコメントやクラスコメントなどは、JavaDocやPHPDocで形式が決まっているものがありますので、その部分はルールに従ってください。
ここでは、処理を記述したコードの途中に入れるコメントを扱います。

コメントは詳しく書けばよいというものでもありません。
たくさんコメントを書くと、プログラムの修正時にコメントの修正もたくさん発生するからです。

以前、開発チーム内でメンバーのコードレビューを行った時、記述したコード1行ごとに全部にコメントを追加しているという極端な例がありました。
すでに記述してしまった分をどうするか判断に迷いましたが、あとあとのことを考えて、結局一部のコメントを削ってもらいました。

もう一つ注意していただきたいのは、文法的な説明は基本的に不要だということです。
コードを読むのは、そのプログラミング言語を理解している人です。
あえて分かりやすく説明すると、「変数xに3を加算して、変数yに代入する」というようなコメントは無駄以外の何物でもありません。

次のように考えると良いと思います。
変数名や関数名を適切に命名することにより、どんな処理が記述されているか把握しやすくなっていることを前提に、それを補足する情報として簡潔なコメントを記述する。
そして、処理が複雑で分かりづらいところには、詳しい情報を付け足します。
また、フレームワークのルールにより注意が必要な点などは、例外的に文法的な説明も加えます。

自分が書いたコードでさえ、しばらく経ってから読み直すと、よく覚えていないものです。
どんな説明を入れておくと、忘れた頃に読み返した際に役立ちそうかを想像して、コメントを追加するようにしてください。

最後に

いろいろ書いてきましたが、社内や開発プロジェクトでルールが決まっていたり、クライアントから指示がある場合には、それに従ってください。

ここで書いたことが、これからのみなさんのコーディング作業に少しでも役立つことがあれば幸いです。