はじめに

このシリーズでは、コードを保守するにあたって重要となる、コードの読みやすさについて考えます。

保守しやすいコードを書くのに必要となる知識には、扱う言語の知識の他にも、設計論やデザインパターン、アーキテクチャなど、さまざまなものがあります。

これらのことを学ぼうと、インターネットで記事を探してみたり、誰かにすすめられた書籍を手にとったりしてみても、どの手法が今の自分の悩みを解決するものなのか、わからないということもあると思います。

筆者も同じような経験をしてきました。そんな中、「読みやすさ」について考える上で、特に重要であると感じたものについて、ここでは触れていきます。

• 最初は良くても、時間が経つに連れて、どんどん保守しづらくなってしまう
• コードレビューで指摘をされても、どう直したらいいのかわからない

こんな悩みを持っている方に、このシリーズが少しでも手助けになれば幸いです。

このシリーズでは、「こういうコードはこう直したほうが良い」といった、具体的なことにはあまり触れません。どちらかといえば、意識したほうが良いことや、心構えのようなことについて、重点的に触れています。

読みやすいコードの書き方について、具体的なことを知りたい方は、「読みやすいコードのために」シリーズも読んでみてください。

コードの読みやすさは、なぜ必要？

そもそも、なぜコードに読みやすさが求められるのでしょうか。

「成果物は、正しく動作するアプリケーションなのだから、どう書かれていようが、正しく動けば問題ない」と考える人も、少なからずいることでしょう。

しかし、そうではありません。

読みづらいコードや、複雑でわかりにくい処理は、後から読み返したときの理解を妨げ、開発効率を低下させます。どういう動きをするのかが理解しづらいため、機能の追加や修正を行う際に、無駄な労力をかけることになるのです。

不具合が起きたときも、どこに問題があるのかを、特定することが難しくなります。不具合箇所の発見が遅れ、修正に時間がかかるようになるため、さらに効率を下げる要因となってしまいます。

書く時間 < 読む時間

一般的には、自分でコードを書いている時間より、読んでいる時間のほうが長い、と言われています。読んでいる時間には、実装後に自分が読む時間の他にも、チーム開発などの場合で、自分のコードを自分以外の他人が読んでいる時間も含んでいます。

動作確認のために、単に処理の内容を追う場合もそうですが、コードを修正したり、処理を追加する場合にも、内容を理解するために読むことになります。

ひとまとまりのコードを読む時間は、それほど長い時間ではないかもしれません。ですが、それが何十回、何百回と繰り返されたとき、その時間はかなりの時間になるはずです。

コードが読みやすい状態に保たれていれば、この時間を短縮することができ、結果的に開発効率を上げることに繋がります。

また、内容を理解しやすくなるので、コーディングのミスや、不具合を発見しやすくなるという利点もあります。

これらのことから、コードを書くときは、「書きやすさ」よりも「読みやすさ」のほうに意識をおいて書くとよいでしょう。

分散するドキュメントをどうする？

通常、コードを書くときは、なんらかの仕様を元にして書かれます。

その仕様は、文書として渡されたり、あるいは、タスク管理ツールなどのチケットに書かれていたりします。

しかし、開発が進むに連れて、仕様は更新されていきます。仕様が更新されれば、当然、コードも更新されます。

やがて、そのコードの元となった仕様が、ドキュメントのどこに書いてあるのかわからなくなる、といったことも起こるかもしれません。

次のような経験をしたことのある方も、少なくないと思います。

資料がエクセルで送られてきたけど、最新の仕様がどこにあるのかわからない。コードとエクセルの往復が嫌で、コードにコメントを残すようにしてみたら、逆にコメントで溢れてしまい、重要な情報が埋もれてしまう。Issueやwikiに書いてみても、やはりコードとそれらを見比べる作業が煩雑になる。そうすると時間が経つに連れて保守されなくなり、古い情報だけが残り続ける。

コードとドキュメントの往復を減らしてくれる方法はないでしょうか？

コードがドキュメントであると考える

当たり前の話ですが、アプリケーションのコードは、そのアプリケーションを動かすために必要となる、さまざまな命令が書かれています。逆にコードに書かれていないことは、絶対に実行されません。一連の動作の中で、どの処理が実行されて、どの処理が実行されないのかということが、コードを読むことで明らかになります。

もし、コードが読みやすい状態で保たれていれば、コードを読むだけで、効率的に仕様を把握することができるようになります。ということは、コード自体がアプリケーションのドキュメントである、と考えられるのではないでしょうか。

もちろん、ドキュメントとコードでは、その役割が違います。ドキュメントを書かなくてもいいということではありません。そうではなくて、仕様が読み取れないようなコードと苦戦しつつ、コードとドキュメントを何度も往復するよりは、コードから仕様を読み取れたほうが、スムーズに開発を進めることができます。

他人に読まれることを意識する

ドキュメントは、「誰か」に何かを伝えるために書くことが多いです。コードをドキュメントと考えるなら、そのコードも「誰か」が読んだときに、意図が伝わりやすいように書かれているべきです。

「誰か」は、一緒に働くチームメンバーであったり、OSSの場合は見ず知らずの人かもしれません。これらの人は、コードが実装された背景を知りません。そのコードに書かれていることしかわからないのです。

そういう意味では、実装から数カ月が経って、背景を忘れてしまった自分自身も、「誰か」のうちの一人となり得るでしょう。他人のためにわかりやすいコードを書くというのは、自分自身のためでもあると言えます。

日本語などの自然言語でドキュメントを書く場合、読み手に伝わりやすいようにしたり、読み手が意図しない解釈をしないように、いろいろな工夫をすると思います。

たとえば、わかりづらい言い回しを避け、伝えたいことをシンプルに書くようにします。また、文意をより伝わりやすくするために、文章の構成を考えたりもします。混乱を招かないよう、表記ゆれがある箇所は統一する、といったこともあるでしょう。

コード自体がドキュメントである、と考えるのであれば、文章を書くのと同じようにコードを書けば、読み手に伝わりやすいコードを書くことができる、と考えられます。

わかりづらい処理を避け、ひとつひとつの処理をシンプルにする。意図が伝わりやすいように、関数の粒度や命名を工夫する。同じような値を扱う変数名は、できるかぎり統一する。

このように意識しながらコードを書いていれば、自然と読みやすいコードになっていきます。

コードに意図を持たせ、後から読んだ人に伝わりやすくする方法については、「読みやすいコードのために」シリーズを参考にしてみてください。

【ワンポイント】セルフレビューを行う

これは筆者の経験則なのですが、実装者として、コードと向き合っているときよりも、レビュアーとして、誰かのコードを読んでいるときのほうが「コードの意図が伝わるかどうか」を重点的に見ることができると感じています。

筆者は、これを活かして、GitHubにプルリクエストを送った際、File Changeタブのプレビュー機能を使ったセルフレビューを行っています。

コードを俯瞰して、客観的に見ることができるので、自分が書いたコードの読みづらい部分を見つけやすくなります。

実際、プルリクエストを送ったすぐあとにセルフレビューをして、読みづらい部分や、後々問題になりそうな処理を修正することがよくあります。

普段自分が書いたコードを読み返す習慣のない人は、眺めるだけでもいいので、一度試してみることをおすすめします。

まとめ

第1回目では、「読みやすいコード」が持つメリットをあげました。「読みやすいコード」は、メンテナンス性に優れています。実案件でも、機能追加や修正がしやすく、継続的にリファクタリングをできたことで、コードを書く上では大きなトラブルもなく進めることができました。

さらに、コードから仕様が読み取りやすいこともメリットです。

筆者が関わっているプロジェクトは、かなり多くの機能を備えたWebアプリケーションで、クライアントと開発者との間で、日々、多くの機能要件がやり取りされています。なかなかタフな経験ではありますが、このプロジェクトを通じて、コードから仕様が読み取りやすいと、作業が効率的になることを実感しました。

また細かなことですが、プロジェクトマネジメントの点からというと、新たな機能追加の要望がきたとき、コードを見て作業時間や難易度を比較的正確に見積もることができたのが助かりました。

次回は、読みやすいコードをどのように書けばよいか、さらに話を進めていきます。