株式会社クリアコード > ククログ

ククログ

«logalimacs 1.0.0 をリリースしました 最新 logalimacs 1.0.1 をリリースしました»
タグ:

リーダブルコードの解説

注: 記事中の「解説」の部分のライセンスは「Creative Commons 表示 - 非営利 - 継承」です。「解説」は「クリアコード」(「ClearCode Inc.」)によって変更されています。変更前の原著作者は「オライリー・ジャパン」です。「Creative Commons 表示 - 非営利 - 継承」なので再配布や変更や翻訳などはライセンスに従って自由に行えますが、営利目的で利用することはできません。

The Art of Readable Code (Theory in Practice)(Dustin Boswell/Trevor Foucher)の翻訳である「リーダブルコード」が今月(2012年6月23日)発売されます。すでに予約できるようです。

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)
Dustin Boswell/Trevor Foucher/須藤 功平/角 征典
オライリージャパン
¥ 2,592

本書の内容は原書の紹介記事を参照してください。

日本語版の訳者は角さんです。これまでの訳書と同様にとても読みやすく訳されています。翻訳なので読みにくいのでは…と心配する必要はありません。良いコードを書きたい人なら読んでみるべきです。

日本語版にはクリアコードの須藤が書いた「解説」が付いています。これは原書にはない内容で、日本語版のために新規に書かれた文章です。「解説」をできるだけ自由に利用できるように、編集の方*1にお願いして「解説」のライセンスは「Creative Commons 表示 - 非営利 - 継承」にしてもらいました。そのため、ククログに少し変更したバージョンを紹介できることになりました。ありがとうございます。

「解説」の解説

「リーダブルコード」の「解説」の少し変更したところとライセンスについて少し解説します。

以下の「リーダブルコード」の「解説」は書籍に載っているバージョンから以下のように変更されています。

  • 読みやすい → リーダブル(ただし、コードに関する文脈のときだけ)
  • 読みやすいコード → リーダブルコード

これは、先日、訳者の角さんと話したときに次のような話を聞いたためです*2

タイトルは「読みやすいコード」ではなく、あえて「リーダブルコード」にした。これは「リーダブルコード」という聞きなれない言葉にすることで、読んだ人に「リーダブルコード」というものについて注意して欲しいからだ。今のプログラマーは普通に「リファクタリング」という言葉を使っていて、「コードをよくすること」がより当たり前になっている。それと同じように、読みやすくないコードを見たら「それリーダブルじゃないよね」とか読みやすいコードを見たら「これリーダブルコードでいいね!」というようなことが自然に言われるようになって、「読みやすいコード」がより当たり前になるといい。

これは応援したくなる話だったので、「解説」の中の「読みやすい」・「読みやすいコード」と書かれている部分は「リーダブル」・「リーダブルコード」としてあります。変更前のものは日本語版を参照してください。

このように、以下の「解説」は日本語版の「解説」を変更して再配布したものになります。元の「解説」のライセンスは「Creative Commons 表示 - 非営利 - 継承」で原著作者は「オライリー・ジャパン」です。そのため、この変更された「解説」のライセンスも「Creative Commons 表示 - 非営利 - 継承」になります。変更された「解説」の原著作者は「クリアコード」(「ClearCode Inc.」)です。

それでは、「リーダブルコード」の「解説」です。9ページ分なのでそこそこ長いです。

解説

須藤 功平

読んでみていかがだっただろうか。プログラマにとってとても大切な「リーダブルコード」を書くということを「理解しやすく」伝えていたはずだ。

本書は元の英語も読みやすく書かれている。少し英語を読める人なら原書でも読めるだろう。そんな原書のいいところをしっかりと残して読みやすい日本語にしたのが訳者の角さんだ。角さんは本書以外にもソフトウェア関連の訳書が数冊あり、どれも読みやすい日本語になっている。角さんの訳の特徴は、読みやすい日本語と時折はさんでくる(わかる人にはわかるくらいのちょっと)有名な言葉だ。本書を読んでニヤリとした人もいたのではないだろうか。やわらかい言い回しでまじめな話をしながら時折ユーモアあふれる挿絵をはさむ本書の訳者として、角さんはまさにうってつけの存在だ。

読みやすい日本語だし、技術的に難しい内容でもないので、サクサク読めただろう。でも、難しくない内容だからといって軽視していいわけじゃない。本書に書いてあることはとても大切なことだ。あなたがこれからプログラマとして信頼してもらえるコードを書くかどうかは本書に書いてあることを身につけるかどうかにかかっていると言ってもいい。もし身につけていないなら、少なくとも私は信頼しない。

そんな本書の内容を身につけて、自然にリーダブルコードを書けるようになるための3つのステップを紹介しよう。

  • 実際にやる
  • 当たり前にする
  • コードで伝える

まず、実際にリーダブルコードを書く。はじめはうまくいかないだろうが、本書を読み返しながら意識してリーダブルコードを書く。リーダブルコードを書けるようになってきたら、「リーダブルコードを書くことが当たり前」にする。リーダブルじゃないコードなんてありえない。そんな状況だ。そんな状況でリーダブルじゃないコードが入ってきたら、どうしたらリーダブルになるかをリーダブルコードで伝える。「リーダブルコードとはこう書くんだよ。」そういうことをリーダブルコードで伝えるんだ。ここまでくれば、自然にリーダブルコードを書けるようになっているだろう。

さぁ、それぞれのステップの具体的なやり方を紹介しよう。

実際にやる

まず 1 つめのステップは、実際にやるということだ。

当たり前だけどこれはとても大事なことだ。(本書の内容も当たり前だけどとても大事なことだったね。)本書の内容を実践して、これから書くコードはリーダブルコードにしよう。実際にやるとはじめて気づくことがたくさんある。

実際にやるとぶつかること

まず、内容を活かす場所がぜんぜんないって思うだろう。でも、それはあなたの書いたコードがすでにリーダブルだからじゃない。単に「気づかない」からだ。本書を読んでいるときは次々と出てくる小さなコードを読みながら「たしかにここはそう変えた方がいいな。ふむふむ。」なんて読んでいただろう。読みながらあなたが「ふむふむ」言っていられたのは著者がわかりやすく書いてくれていたからだ。でも、実際のコードにはそういうヒントはない。著者のヒントがないんだから、実際のコードを読んでいるときは見逃してしまうだろう。それが自分が書いている真っ最中のコードならなおさらだ。読む側の視点じゃなくて書く側の視点でコードを見ているんだから。

ウソだと思うなら新しくリーダブルコードを書いて私にコードを見せてみるといい*3。リーダブルコードになっているかどうか、よっぽど気にして書かないと何かしらツッコミが入るだろう。もちろん、イジワルするつもりじゃないから、リーダブルコードだったらちゃんと「すばらしい!」とコメントするつもりだ。

他の人に読んでもらう

今、さらっと私に見せてみるといいなんて書いたけど、自分が書いたコードを人に読んでもらうということは、リーダブルコードを書くためのとてもいい機会になる。本書の中で、「他の人がこのコードを読んでどう思うか」ということを何度も気にしていたのを覚えているだろうか。

だから、読む人は私じゃなくたっていい。仲間と一緒にコードを書いているなら、仲間に見てもらうのがいいだろう。でも、そのときは「気になるところがあったら遠慮せずに言ってくれ!」と念を押すことを忘れずに。同じコードを触っている仲間なら多少理解しづらいコードがあってもなんとなくわかってしまう。そうすると、本当はリーダブルじゃないコードなのに気づいてもらえないかもしれない。

できれば、仲間にも本書を読んでもらって、どうすればリーダブルコードになるかを共有しておくのがいい。仲間と一緒に実践できるとなおいい。仲間と一緒に始めれば、「今のコードはリーダブルだね!」といった話や「今のコードをこう変えればもっとリーダブルになると思うんだけどどうだろう?」といった話ができる。そうなったらより楽しみながら「リーダブルコード」を書けるようになる。まわりにいるすごいプログラマにも意見を聞いてみるといいだろう。「このコードで○○をリーダブルにできなかったんですが、なにかいいアイディアがあったら教えてもらえませんか?」

あなたがリーダブルコードを書こうとしていることがみんなに伝われば、「ここ、もう少しリーダブルにならないかな?」といったフィードバックが増えるだろう。そうすると、あなたの書くコードはどんどんリーダブルになっていくはずだ。(ただし、あなたが素直にフィードバックを聞ければ、だ。自分がリーダブルだと思って書いたコードをリーダブルじゃないと言われるのはつらいことだけど、別にあなたを攻撃しようとしているわけじゃないので落ち着いて素直に聞いてみよう。)

おさらい

自然にリーダブルコードを書けるようになるための1つめのステップは、実際にやるということだ。はじめはどこをよくすればいいかを見つけることが難しい。本書を読み返したり、仲間にコードを読んでもらったりしながら自分で「気付ける」ようになって欲しい。リーダブルじゃないことに気付いたら、リーダブルにする方法は本書に書いてある。ここはそんなに難しい話じゃないはずだ。自分で自分のコードのリーダブルじゃないところに「気付ける」ようになれば、リーダブルコードも書けるようになっているだろう。そうなったら次のステップへの準備はできている。さぁ、次のステップへ進もう!

当たり前にする

次のステップは当たり前にするということだ。

1つめのステップであなたが新しく書くコードはリーダブルになっている。そうすると、既存のコードのリーダブルじゃないところがちらほら目につくようになる。目の前のそれらのコードをリーダブルにしようと意気込んでいることだろう。それはとてもすばらしいことだ!だが注意して欲しいことがある。それは、一時の頑張りだけではリーダブルコードにはならないということだ。もし、それを忘れてしまうとせっかくの意気込みが消えてしまう。それはとてももったいないことだ。

既存のコードをリーダブルにする前にやること

あなたが既存のコードを直し始めたとしよう。でも、仲間たちはその間も新しいコードを書いている。それらのコードはリーダブルコードではないかもしれない。自分だけがリーダブルコードを書いているという状況はとてもつらい。他の人がコードを書くたびにリーダブルじゃないコードが入ってくる。掃除しているそばからゴミを捨てられているような感覚だ。まずは新しく書くコードがリーダブルコードだけになるようにしよう。既存のコードを直すことはそれまでガマンして欲しい。

具体的には、これからあなたが触るコードはリーダブルコードにしていく。まず、新しく書くコードはリーダブルコードで書こう。これはもうできているはずだ。でも、できているからといって油断してはいけない。まだ意識しないとリーダブルコードを書けない状態だから、気を抜くとリーダブルじゃないコードを書いてしまう。気を付けて。

さらに、他の人が新しく書いたコードについても同じくリーダブルコードにしていく。リーダブルじゃないコードだったらその人と相談してリーダブルコードにしよう。既存のコードはそのコードを変更するときにリーダブルコードにしていこう。やり方はわかるはずだ。理解するまでに時間がかかる書き方だったらどうする?名前が曖昧だったらどうする?ピンとこなかったら本書をもう一度読み直してみよう。本書で丁寧に説明している。

これを続けてリーダブルコードを書くことを当たり前なことにしよう。誰かがリーダブルじゃないコードを書いたら、「ここ、少しリーダブルじゃないよね?」と指摘する人がいるのが自然な状態だ。そうなれば習慣になったといえる。ここまできたら既存のコードをリーダブルにするやり方を考え始めてもいいだろう。(ただし、1年かけてリーダブルにするというようなやり方がでてきたら危険な合図だ。そのやり方をもっと小さく分割したりできないか考えてみるべきだ。ただ、この話題は本書の範囲を超えるのでまたの機会に。)

続けることが大事

本書で説明しているリーダブルコードを書くための方法は小さな基本的なことばかりだ。ソフトウェア全体をキレイにまとめるパターンなんかではない。1つの方法ではコードが少しキレイになるだけだ。しかし、これらの方法をコード全体に適用していけばコード全体がキレイなリーダブルコードになる。一時的にコードをリーダブルにしようというスタイルではなく、継続してコードをリーダブルにしようというスタイルでコードを書いて欲しい。

明日、あなたが読むコードは今日まであなた(と仲間たち)が書いたコードだ。明日、見たくないコードを見なくてもすむようにするには、今日、リーダブルコードを書くことだ。

リーダブルコードを書くということはたまに思い出してやることではない。習慣にして常に実践することなんだ。それを忘れないで欲しい。それが実践できれば明日もずっとその先も楽しくコードを書けるはずだ。

リーダブルコードが当たり前の世界へようこそ。さぁ、次のステップへ進もう!

コードで伝える

最後のステップはコードで伝えるということだ。

リーダブルコードが当たり前になったら、その先なんてないと思うかもしれない。だって、みんながリーダブルコードを書いているんだから。これ以上なにを求めると言うんだ。

リーダブルコードがもっと当たり前であり続けるために

でも、あなたには仲間が増える。それは若い子だったり新人だったりするかもしれない。新しい仲間は本書を読む前のあなたと同じだ。最後のステップでは新しい仲間を手伝って、新しい仲間もリーダブルコードを書くことが当たり前になれるようにする。ちょうど本書の著者があなたにやってくれたように。

本書はたくさんの人に伝えられるように一般的な例を使って書かれている。それでもわかりやすく書かれているが、実際に自分たちが触るコードを使って説明した方がより実感がわくし、納得もしやすい。新しい仲間にどうすればリーダブルコードになるかを伝えるために自分たちが書いているソフトウェアを使おう。自分たちのソフトウェアをリーダブルコードで書くことで、どうすればリーダブルコードになるかを伝えるんだ。

コミットメールのススメ

ソフトウェアはコードの変更の積み重ねで作られている。それを管理するためのソフトウェアが Git や Subversion などのバージョン管理システムだ。もちろんあなたも使っているはずだ。まだ使っていないなら急いで使えるようになろう!リーダブルコードを書こうと試行錯誤するときにとても役立つ。仲間とコードを共有することにも便利だ。

よし、バージョン管理システムは用意できたね。それでは、コミットメールも用意しよう。コミットメールとはバージョン管理システムに変更を追加(コミット)したときに送られる通知メールのことだ。コミットした人は誰か、どんな変更だったかの説明なんかが書かれている。これを読めばどんな変更が入ったか、雰囲気がわかる。具体的な変更点(diff)は入ったり入らなかったりする。私はdiffも入れることを強くオススメする。diffもあるとどのようにコードが変更されたかまですぐに確認できる。diffを入れないとgit log -pやsvn diff、Webブラウザでリポジトリブラウザを開くなどの追加のひと手間が必要になる。コードを読むための敷居はできるだけ低くする。これはとても大事なことだ。コードを読むことが面倒になると、「どうせ誰も読まないって!」となってしまう。これでは「どうしてリーダブルコードを書かなきゃいけないの?」に逆戻りだ。

まずはあなたが読む

diff入りのコミットメールは仲間みんなに届くようにしよう。はじめは誰もあなたのdiffを読んでくれないかもしれない。ここであきらめちゃダメだ。まずはあなたが仲間のdiffを読もう。diffを読んで、リーダブルじゃないコードがあったら教えてあげよう。diffにはコード全体ではなく変更箇所の周辺しか含まれていない。「diffだけ読んでリーダブルかわかるわけないじゃん!」と思うだろう。でも、diffだけ読んでもリーダブルなコードにしないといけないんだ。もちろん、diffだけでその周辺のロジックまで正しいかどうかはわからないことの方が多いだろう。それでもdiffだけでリーダブルなコードを書いているかどうかはわかるんだ。

本書の内容を気にして書かれているコードはdiffになってもリーダブルだ。小さなdiffの中だけでtmpという変数名を使っているならそれは本当に一時的な変数なんだろう。このようなコードは適切な名前がついていてリーダブルだ。でも、大きなdiffの中でtmpという変数名を使っているなら要注意だ。単にいい名前をつけなかっただけかもしれない。思い出して欲しい。本書の中でたくさんのサンプルコードが出てきた。それらのほとんどは10行未満のコードだった。でも、そのコードを読んで、リーダブルコードとそうじゃないコードがどう違うかが伝わったはずだ。だったらdiffを読んだってわかるはずだ。

まずはあなたがdiffを読んで仲間にフィードバックしよう。「こうすればもっとリーダブルになるんじゃないかな?」それを続けていれば仲間もあなたのdiffを読んでくれるようになるはずだ。あなたがコミットするときはリーダブルなdiffになるようにコミットしよう。仲間のdiffを読んでいたあなたはどういうdiffがリーダブルかはわかっているはずだ。

わかりやすい目安はこうだ。1つのdiffに1つのことを。もし、あなたが本書中のコードをリーダブルにする方法でコードを変更したときは、1つの方法ごとにコミットすること。「2.1 明確な単語を選ぶ」と「4.4 縦の線をまっすぐにする」を一緒にコミットしてはいけない。「2.1 明確な単語を選ぶ」で1回、「4.4 縦の線をまっすぐにする」でもう1回コミットするんだ。そう、「11章 一度に1つのことを」だ。

添削コミット

他の人がリーダブルじゃないコードをコミットしたら、「こうすればもっとリーダブルになるんじゃないか」というコードをコミットしよう。そして、「今コミットしたように変更するともっとリーダブルになると思うんだけどどうかな?」と声をかけてみよう。ただし、他の人のコードに手を入れるというのが「当たり前」の文化でない環境の場合はいきなりやると角が立つかもしれない。(バージョン管理システムを使っているならコードを共有する文化は根付いていると思うけど!)その場合は、まずは「このあたりのコードを整理していい?」と事前に確認してからやるのもいいだろう。

これは私が「添削コミット」と呼んでいるものだ。「添削」だと上から目線のイメージがあるので「提案コミット」と呼ぶほうがいいかもしれない。

どうして最後のステップで「添削コミット」をオススメしているのか。それは、添削コミットではまさに「リーダブルコード」になっていなければいけないからだ。「添削コミット」はコードで自分が意図していることを伝えるということだ。伝えるためには他の人が理解しやすいコードでなければいけない。これはまさに本書で言っていることだ。

本書はリーダブルコードの書き方をわかりやすく伝えている。どうしてわかりやすいのか。それは、「どうしてこの書き方がいいのか」という「理由」だけでなく、そのための「具体的な書き方」という「方法」も一緒に伝えているからだ。たとえ「理由」だけがわかってもそれを実現するための「方法」がわからなければ実践できない。例えば、「関数を理解しやすくなるのでいい名前をつけましょう」だけでは実践できない。「いい名前」だけでは抽象的すぎて人それぞれの「いい名前」になってしまう。

添削コミットではリーダブルコードにするための「具体的な書き方」がコミットの内容そのものになる。コミットメッセージにはどうしてこの書き方の方がリーダブルなのかの「理由」を書く。こうすることで本書でやっているような伝え方を実現できる。修正しているので実際にコードがよくなるし、具体的な実例をつけてよりリーダブルなコードを伝えることができるので、ぜひやってみて欲しい。

もちろん、添削コミットをする前にその人にも本書を読んでおいてもらうといいだろう。リーダブルコードについて、より伝わりやすくなるはずだ。

おさらい

自然にリーダブルコードを書けるようになるための最後のステップは、コードで伝えるというだ。これまでのステップではあなたがリーダブルコードを書けるようになることを重視していた。最後のステップではあなたがリーダブルコードを伝えられるようになることを重視する。あなたの意図をコードで伝えられるなら、それは本当にリーダブルコードになっているということだ。

あなたがリーダブルコードを伝えるためには、自分たちが書いているソフトウェアで伝えるのが一番わかりやすい。一般的な例題で伝えるよりもピンとくる。自分たちのソフトウェアを材料にするために、みんながより自然にコードを読む環境を作る。その方法としてdiffを共有する。diffをただ流すだけにしてはいけない。まずあなたがdiffを読んでそこからリーダブルじゃないところを見つける。そして、その改善案をコードで伝える。リーダブルコードで伝える。具体的な改善案とリーダブルになる理由でリーダブルコードを伝えるという方法は本書で著者たちが使っていた方法だ。今度はあなたがリーダブルコードを伝える番だ。

最後に

解説として、本書の内容を身につけて自然にリーダブルコードを書けるようになるための3つのステップを紹介した。3つめのステップまでいけば「リーダブルコードを書かないなんてありえない!」となる。そうなったら著者が本書の最初で書いていたようなことが現実になる。

君はきっと優秀なプログラマになれるはずだ。自分の仕事に誇りを持ち、周囲のみんなが喜んで使ってくれるような、バグの少ないコードを作り出せるようになる。

私はリーダブルじゃないコードを書く人とは一緒にコードを書きたくない。私がリーダブルじゃないコードを触るときは、まず、見た目を直してリーダブルにする。そう、本書の「第I部 表面上の改善」に相当することだ。本書を読んで「わかってるな!」と思ったところは、まず「第I部 表面上の改善」を持ってきているところだった。

あなたも本書の内容を活用して、リーダブルコードを書くプログラマとなってくれることを期待している。

リーダブルコードを書いて、自分が書いたコードを忘れてしまっても問題ないようにして欲しい。リーダブルコードを書こう。忘れてもいいコードを書こう。

「自分が書いたコードってどのくらい覚えているんですか?」

「ほとんど覚えていないですよ。」

「直すときどうするんですか?わからなくなってるじゃないですか。」

「忘れても見たら簡単にわかるように書いておくんですよ。」


須藤 功平(すとう こうへい)

フリーソフトウェアプログラマで、株式会社クリアコード代表取締役(2代目)。社名の命名者でもある。社名の由来は「キレイなコード」。その名の通りキレイなコードを書く会社であろうという意図を込めている。最近は自分がどうやってキレイなコードを書いているかを他の人にうまく伝えるにはどうしたらよいかに興味がある。他に興味があることは立派じゃない盆栽を種から育てること。訳者の角さんと初めて話したのは2005-08-27のLLDNが終わった後のロフトプラスワン前。訳者の角さんと編集の高さんも所属しているたいやき部の部長としても活躍中。

まとめ

以上が「リーダブルコード」の「解説」です。リーダブルなコードに興味のある人は読んでみてください。

解説中にでてきた添削コミットの例を紹介しておきます。Cutterのコミット4ded23dに対応するのは1429aa1...dd6a37fのコミットです。見なおしてみると、「どうしてコミット後の方がよいのか」という理由は1回しか書いていませんね。

コミットにコメントするということに関連しますが、「クリアコードのプログラマーがあなたのコミットにコメントする」という新しいサービスを検討しています。まだ検討を始めたばかりで、実現しないかもしれないのですが、興味のある方はお問い合せフォームからご連絡ください。実現するしないに関わらず、検討後、その結果どうなったかをご連絡します。

お知らせ

2015年3月6日に実践リーダブルコードというセミナーを開催します。この解説で説明している「自然にリーダブルコードを書けるようになる」方法を身につけられるセミナーです。自然にリーダブルコードを書けるチームを目指している方はご利用ください。

*1 訳者まえがきの謝辞にある通り編集はオライリー・ジャパンの高さん。

*2 こんな内容だったというだけで一字一句同じではありません。多少誇張しているかもしれませんが、そのときは角さんが修正してくれるはずです。

*3 連絡先はkou@clear-code.com。もし、Rubyのコードなら、るびま編集部に送ってもいいだろう。コードを添削する企画があるのでそこでコードを読んでくれるはずだ。Rubyist Magazine - るびま magazine@jp.rubyist.net

2012-06-11

«logalimacs 1.0.0 をリリースしました 最新 logalimacs 1.0.1 をリリースしました»
2008|05|06|07|08|09|10|11|12|
2009|01|02|03|04|05|06|07|08|09|10|11|12|
2010|01|02|03|04|05|06|07|08|09|10|11|12|
2011|01|02|03|04|05|06|07|08|09|10|11|12|
2012|01|02|03|04|05|06|07|08|09|10|11|12|
2013|01|02|03|04|05|06|07|08|09|10|11|12|
2014|01|02|03|04|05|06|07|08|09|10|11|12|
2015|01|02|03|04|05|06|07|08|09|10|11|12|
2016|01|02|03|04|05|06|07|08|09|10|11|12|
2017|01|02|
タグ:
RubyKaigi 2015 sponsor RubyKaigi 2015 speaker RubyKaigi 2015 committer RubyKaigi 2014 official-sponsor RubyKaigi 2014 speaker RubyKaigi 2014 committer RubyKaigi 2013 OfficialSponsor RubyKaigi 2013 Speaker RubyKaigi 2013 Committer SapporoRubyKaigi 2012 OfficialSponsor SapporoRubyKaigi 2012 Speaker RubyKaigi2010 Sponsor RubyKaigi2010 Speaker RubyKaigi2010 Committer badge_speaker.gif RubyKaigi2010 Sponsor RubyKaigi2010 Speaker RubyKaigi2010 Committer
SapporoRubyKaigi02Sponsor
SapporoRubyKaigi02Speaker
RubyKaigi2009Sponsor
RubyKaigi2009Speaker
RubyKaigi2008Speaker