You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert

プログラムを書いていると問題に遭遇します。問題に遭遇したときはエラーメッセージが問題解決の重要な情報になります。しかし、エラーメッセージがあるだけでは問題解決にはつながりません。問題解決に役立つエラーメッセージとそうでもないエラーメッセージがあります。 ここでは、Rubyでの例をまじえながら問題解決に有用なエラーメッセージを紹介します。ライブラリなど多くの人が使うようなプログラムを作成する場合は参考になるかもしれません。 問題解決への道 問題に遭遇してから問題を解決するまでには以下の順で作業をする必要があります。 問題の把握 問題の原因の調査 原因の解決方法の検討 解決方法の実装 役立つエラーメッセージがあると「1. 問題の把握」、「2. 問題の原因の調査」、「3. 原因の解決方法の検討」がはかどります。 問題の値を示す エラーが発生すれば問題が起こっている事実は把握できます。次にすること

クリアコードでは、社名からわかる通り、日頃からクリアなコードを書くべく日々コードと向き合っています。そのために「みんながみんなのコードを読む文化」を維持しています。 クリアコードでは自分たちがクリアなコードを書くだけではなく、自分たち以外の人たちがクリアなコードを書くことを支援したいと考えています。そのために、他社の開発チームに「みんながみんなのコードを読む文化」を根付かせる支援をするコミットへのコメントサービスも提供しています（導入事例）。また、クリアなコードを書くために実践しているノウハウを文書化して公開しています。例えば、以下のようなノウハウです。 よいコードの書き方に関して 名前のつけ方 - ククログ(2012-06-28) ifとreturnの使い方 - ククログ(2012-03-28) クリアなコードの作り方: 余計なことを書かない - ククログ(2012-05-21) デバッ

しばらく人前で話す予定がないので、講演者が本当に話したかったスピーチを残しておきます。 実は、日本Ruby会議2011で話したことは札幌Ruby会議02で話したことと札幌Ruby会議03で話しかけたことの続きでした。話の流れも札幌Ruby会議02と同じ流れにしました。一番伝えたいことは話しの真ん中に持っていき、その後に実例を伝えるという流れです。 札幌Ruby会議のころは「伝えること」について考えていました。 私がプログラミングを始めたのは大学のころ1で、世間で活躍しているプログラマーよりだいぶ遅いです。でも、プログラミングが好きでたくさんプログラムを書いてきました。今では、プログラミングをはじめて10年くらい経ち、だいぶ上手くなってきました。でも、このままだとよくないなぁと思うようになりました。 私は独学でプログラミングを学んできました。本を読んだりコードを書いたり、他の人のよいところを

Rubyではライブラリのリファレンスマニュアル作成のドキュメントツールとしてRDocが標準となっています。これは、古くからあるという理由とRuby本体に標準添付されているという理由からです。しかし、RDocはそれほど活発に開発されていないため、最近のドキュメントツールとして機能不足と言わざるをえません1。どのような機能が足りないのかについては別の機会にします。 数年前からYARD（Yey! A Ruby Documentation Tool）というドキュメントツールが開発されています。YARDはRDocとの互換性を残したまま機能を拡張しているため、RDocからの移行も容易です。実は、YARDは第2回フクオカRuby大賞（SSLの証明書の期限が切れているので警告がでます）に「Improving Documentation in the Ruby Community」というタイトルで応募してい

本当は「…ない」と否定形ではなく「…する」というような肯定形のタイトルにしたかったのですが、すっきりしたタイトルが浮かびませんでした。肯定形で書くと「身の丈にあった機能を使う」です。 このタイトルは、書いている人にとってオーバースペックかどうかではなく、書いているコードにとってオーバースペックかどうかという意味です。初心者だからメタプログラミングはするな、という話ではありません1。やり方をいくつも知っていると、より汎用的なやり方を選択したくなるでしょうが、汎用的かどうかという基準だけで考えるのではなく、そのコードにあったやり方かどうかという基準でも考えましょうという話です。 コードを読む側を経験するとわかりますが、コードを書いた人がどうしてこのようなコードを書いたかを知っているか知っていないかでコードの読みやすさが違います。もちろん、どうして書いたかを知っている方が読みやすいです。例えると

はじめに クリアコードでは、FirefoxやThunderbirdのサポート業務において、ログファイルを使って原因を調査することがあります。 この記事では、その中でも特に「手元の環境では再現できない問題について、実際に問題が起こっている環境でログを取得してもらい、それを分析して原因を推測する」という調査の進め方について、どのように進めるのか、また、その時はどのような点に気をつける必要があるのか、ということに焦点を当てて紹介します。 ここでは具体例として、「ThunderbirdでIMAPのメールアカウントを使用しているときに、Thunderbirdがフリーズしてしまう」という問題の原因を調査する場合を想定します。全体としてThunderbirdの事情に特化した説明になっていますが、ログの出力が関係するあらゆる場面で適用できる一般的なセオリーとしても参照できるはずなので、そのような視点でも読

以前、読みやすいコミットにする方法としてコミットメッセージの書き方と小さくまとまったコミットの具体例を紹介しました。今回は、小さくまとまったコミットにするためのより一般的な方法の案を紹介します。案としているのは、広く使えそうな気がしますが、思いついたばかりでまだ実例がないためです。この方法が使えそうな気がしたらぜひ試してみてください。 どのくらいのコミットが読みやすい適切なサイズかというのはケースバイケースのことがほとんどです。以前紹介した具体例が使えることは日に何回かあるでしょうが、1日に二桁くらいはコミットするはず1なので、コミットの大半はケースバイケースで判断していることになります。では、ケースバイケースで判断しているときはどのように判断しているのでしょうか。感覚的にはケースバイケースで判断しているときも何かしら一般的な判断基準を使っていそうです。 そこで思いついた（気付いた）のが今

「同じことは同じように書く」ことがどうして大事かを説明します。 具体例: returnの有無 先日、DevLOVE運営チーム主催のリーダブルコードイベントが開催されました。イベントの前半はリーダブルコードの訳者である角さんによるリーダブルコードの紹介で、後半は参加者が「リーダブルコードとはどういうコードか」をディスカッションしました。ディスカッションでは実際に参加者が書いたコードを読みながら「ここはリーダブルだね」「ここはこうした方がもっとリーダブルじゃないか」といったことを考えました。 さて、その中で使ったコードを見ながら「同じことは同じように書く」ことがどうして大事かを説明します。ここで使うコードはdproject21/yaruo_tdd_triangleのtriangle.rbです1。 class Triangle attr_accessor :a, :b, :c def is_eq

物事の進め方や問題の解決の仕方などを決めるとき、他の人に相談します。しかし、いざ相談してみると、うまく相談できずに、もどかしい思いをしたり、相談の時間がいたずらに長くなって相談相手に迷惑をかけてしまったりすることがあります。うまく相談できていないときは、自分の状態をうまく伝えられず、相談相手を困らせたり、役に立たないアドバイスをもらったりします。 相談する目的はいいアドバイスをもらうことです。「いいアドバイス」とは、「自分の状態を良くするのに役立つアドバイス」です。いいアドバイスをもらうと、相談した自分の状態をいい方向にもっていくことができるからです。いいアドバイスをもらうためには、相談の仕方に気をつける必要があります。今回は、他の人に相談していいアドバイスをもらうための相談の仕方について説明します。 いいアドバイスをもらうためには伝える情報に気をつける いいアドバイスをもらうためには、相

はじめに わかりやすいコードを書くことはソフトウェア開発において大切なことです。では、具体的にわかりやすいコードとはどんなものでしょうか？その観点はいろいろなものがあります。その中で今回は名前のつけ方に着目します。 コードに名前をつけるということ ソフトウェア開発において、名前をつける作業というのは絶えず発生します。メソッド名、変数名、クラス名、ファイル名などなど。名前をつける機会を挙げたらキリがありません。では、そもそもなぜ名前は必要なのでしょうか？ それはソフトウェアに限らず言えることですが、複数のモノを区別したいためです。例えば、まったく違う処理をする別々のメソッドに同じ名前をつけたらソフトウェアは正しく動きません。それを防ぐためにそれぞれのメソッドにちゃんと名前をつける必要があります。それぞれのモノにそれぞれ違う名前をつけて区別できなければソフトウェアはそもそも動きません。 名前を

はじめに ソフトウェアを作るときには同時にテストも作ります。 テストを動かすことで、ソフトウェアが設計の通り動作しているかを確認できます。もし設計の通りに動作しない場合はテストが失敗し、ソフトウェアに期待する動作と現在の間違った動作が明確になります。 テストをすっきりと書くことができると、テストを読みやすくなり、また、きれいなソースコードのままで新しくテストを追加することができます。 今回は、そのすっきりとテストを書くための方法について説明します。 テストを追加していくと発生する問題 例えば、1つのテストケースの中にいろいろな機能のテストがある場合を考えます。 ここで、ある機能の実装を修正したので、この機能に関するテストを追加しようとしました。 テスト名に「テストのコンテキスト」と「テスト対象」を含めてどのような内容のテストかを示します。 このとき、ある機能に対して様々な動作をテストするこ

FileUtils.mkdir_p assets_path unless FileTest.exist? assets_path このコードを元に、「余計なコードを書かない」ことがどうして大事かを説明します。 余計なコード まずは、どこが余計なコードなのかを考えてみましょう。このコードではFileUtils.mkdir_pとFileTest.exist?メソッドを使っています。 FileUtils.mkdir_pは引数で指定されたディレクトリがなかったら親ディレクトリも含めて作成するメソッドです。すでにディレクトリが存在した場合は何もしませんし、エラーにもなりません。mkdir_pというメソッド名はmkdir -pコマンドが由来でしょう。 FileTest.exist?は引数で指定されたファイルが存在したら真を返すメソッドです。 このコードではunless FileTest.exist?の

オフィス文書形式が要求されるようなドキュメントではなくて、自分が開発したライブラリのドキュメント（リファレンスマニュアルやチュートリアルなどライブラリのユーザーが読むためのドキュメント）の話です。以下の「ドキュメント」もそのような意味で使っています。 使いやすいライブラリを開発したかったらプログラムだけではなくドキュメントも書くべきです。 なぜドキュメントを書くか ドキュメントを書く習慣があるかどうかは開発者によってあったりなかったりです。使っているプログラミング言語に相関がある気もしますし、リリースするかどうかに相関がある気もします。理由はいろいろあるでしょうが、ドキュメントを書く習慣のない開発者の方が多いでしょう。 書かない理由はこんな感じでしょうか。 面倒。 自分しか使わないからいらない。 どのように書けばよいかわからない。（どのツールを使えばよいかわからない。） 一方、書く理由はこ

最近読んだRubyのコードではYARDのコードがキレイでした。 さて、長いメソッドは不吉なにおいがするからメソッドを分割するなどして短くしましょうとはよく言われることですが、ここでいう「長い」とは「縦に長い」ことを指していることがほとんどです。長いのが問題なのは縦に長いときだけではなく横に長いときもです。 縦に長いメソッド まず、どうして縦に長いメソッドが問題かについてです。縦に長いメソッドには「処理を把握しづらい」という問題がある可能性が高いです。 どうして処理を把握しづらいか 処理を把握しづらい原因はいくつかあります。例えば、抽象度が低いのが原因です。 メソッドが縦に長くなっているときは、多くの処理が行われていることがほとんどです。これらの処理はメソッドになっていないため名前がついていません。処理に名前がついていない場合は実装を読まないとなにをしているかがわかりません。 せっかくなので

注: 記事中の「解説」の部分のライセンスは「Creative Commons 表示 - 非営利 - 継承」です。「解説」は「クリアコード」（「ClearCode Inc.」）によって変更されています。変更前の原著作者は「オライリー・ジャパン」です。「Creative Commons 表示 - 非営利 - 継承」なので再配布や変更や翻訳などはライセンスに従って自由に行えますが、営利目的で利用することはできません。 https://amazon.co.jp/dp/B0064CZ1XEの翻訳である「リーダブルコード」が今月（2012年6月23日）発売されます。すでに予約できるようです。 https://amazon.co.jp/dp/4873115655 本書の内容は原書の紹介記事を参照してください。 日本語版の訳者は角さんです。これまでの訳書と同様にとても読みやすく訳されています。翻訳なので読

もう1年以上前になりますが、コミットメッセージの書き方を説明しました。ざっくりまとめると、以下のことを説明しています。 わかりやすいコミットメッセージがいかに大切か どのようなコミットメッセージがわかりやすいか（具体例付き） この説明をしてからも、日々コミットしていくなかで新たに得られた「どうすればもっとわかりやすいコミットメッセージになるか」という知見が増えていました。これは、コミットへのコメントサービスの提供を開始した1ことも影響しています。このサービスでは、コミットへコメントするときに「どうして自分は他の書き方よりもこの書き方をわかりやすいと感じるか」を説明しています。その過程で「なんとなくこっちの方がよさそう」だったものを「具体的にこういうときにこう感じるのでこっちの方がよさそう」と何かしら理由を考えるようになりました。これにより、今までそれぞれの開発者でなんとなくだった考えが共有

コミットメッセージの書き方ではコミットをわかりやすくするためには以下の2つの条件を満たす必要があると書きました。 コミットの内容が分かりやすく説明されていること コミットの内容が小さくまとまっていること このうち「コミットの内容が分かりやすく説明されていること」についてはすでに説明済みです。今回は「コミットの内容が小さくまとまっていること」について説明します。 めざすところ 単純にコミットの内容を小さくするだけではわかりやすくなりません。それでは、どのような基準で小さくすればよいのでしょうか。 よく言われることは1つのコミットには1つの小さな論理的にまとまった変更だけにする、というものです。たしかにこれは重要です。しかし、これだけを基準とすると、人によっては大きめなコミットになってしまいます。人それぞれで論理的なまとまりの大きさが異なるからです。 1つのコミットでどうすればよいかを考えるの

はじめに 「分かりやすいコードを書く」、「コードと一緒にテストも書く」等はソフトウェア開発において大切なことです。しかしそれと同じくらい大切なことして「分かりやすいコミットメッセージを書く」があります。これはあまり着目されていなく、見過ごされていることです。 今回は、コミットメッセージの分かりやすさの大切さ、そして、分かりやすくするための書き方を説明します。 コミットメッセージとその大切さ バージョン管理システムとコミット 現在、ほとんど全てのソフトウェア開発ではSubversionやGitなどのバージョン管理システムを使っています。バージョン管理システムを使うことによるメリットというのは、ソフトウェアの変更が記録されていくことにあります。 具体的なメリットは3つあります。 ソフトウェアの調査がしやすくなることです。現時点でのコードと、そして変更の履歴とを組み合わせることで、それらから非常

クリアコードではMozilla製品やRuby関連の開発だけではなく、広くフリーソフトウェアのサポートもしています。もちろん、サポート対象のソフトウェアの多くは私達が開発したものではありません。しかし、それらのソフトウェアに問題があった場合は調査し、必要であれば修正しています。 このようなサポートが提供できるのは、もともと、私達がフリーソフトウェアを利用したり開発したりしているときに日常的に問題の調査・修正をしていたからです。ソフトウェアを利用していると、問題に遭遇することはよくあることです。そのソフトウェアがフリーソフトウェアの場合は、開発者に問題を報告し、可能ならパッチを添えます。このとき、そのソフトウェアの内容を完全に把握していることはほとんどありません。しかし、それでも修正することができます。 それはどうしてでしょうか？今まではどのようにやっているのかを自分達でもうまく説明できなかっ

ソフトウェア開発を支援するために、やりたいことや問題を管理するシステムがあります。例えば、Bugzilla1やRedmine2、GitHubなどがそのような機能を持っています。システムごとにやりたいことや問題の呼び方が違います。例えば、Bugzillaでは「バグ」、Redmineでは「チケット」、GitHubでは「Issue」と呼んでいます。ここではRedmineと同じ「チケット」と呼び方を使うことにします。 今回紹介するのは、後からチケットを見たときに、チケットを書いた時に知っていた情報を思い出せるようなチケットの書き方です。 このような書き方は、プロトタイプのような「作って終わり」とか「短期間の開発」というようなソフトウェアでは必要がないでしょう。また、後述の通り、「チケット駆動開発」にも使えないでしょう。継続的に開発を続けていくソフトウェアの開発のように、やりたいことや問題はあるけど