「コードは設計書だ」と本気で思い直したきっかけ
「詳細設計はありません。現行踏襲で。仕様はソースを読んでください。」
ある現場でこう言われたとき、「あ、これはマズいかもしれない」とうすうす感じていました。
一応、設計書はありました。でも中身はほとんど空っぽで、画面イメージとテーブル定義が少し書いてあるだけ。肝心の処理の流れや、なぜそうなっているのかといった話はほとんど触れられていません。
設計担当に聞いても、返ってくるのはだいたいこんな答えでした。
「現行踏襲なので、細かいところはソースを見てください」
頼みの綱の既存コードを開いてみると、そこには別の種類の絶望が待っていました。
- リファクタリングの形跡がまったくない
- 1メソッドが何十行もダラダラ続いている
- 「〜Manager」「〜Helper」のような名前が乱立していて、責務の境界も分からない
「これをそのまま真似したら、未来の誰も読めないな……」
そう思ったとき、初めて真剣に「コードから設計の意図が読めるようにしないとマズい」と感じて、『プリンシプル オブ プログラミング』を手に取りました。
それまでの自分：設計書に甘えていた
正直に言えば、それまではかなり他人まかせな考え方でした。
- 設計はえらい人の仕事
- 実装者向けチェックリストを満たして、結合テストが通ればOK
こんなノリでやっていました。
「設計書とコードがちゃんと対応しているか」といったところには、ほとんど意識が向いていませんでした。バグ調査で困るたびに、
- 設計書のどこに対応するのかを、時間をかけて探す
- 設計書とコードのどちらが「正しい」のかを、その都度推測する
- JUnitを書きたくても、仕様の本当の意図が分からない
といったつらい作業をしていましたが、「現場ってこういうものだろう」と半ばあきらめてもいました。周りの実装者もだいたい同じ感覚だったので、なおさら疑問を持ちにくかった。
フレームワークの特性もよく分かっていなかったので、Spring がすでに提供している機能を自前で書こうとして、車輪の再発明を連発しました。
- 本当は設定ひとつで済むものを、がんばってコードで実装する
- うまく動かず、デバッグで何時間も溶かす
イライラしながらコードを書くのが「普通」だと、本気で思っていました。
本で刺さったのは「どっちが本物の設計か」という視点
『プリンシプル オブ プログラミング』を読んで、一番刺さったのは、細かいテクニックではなく、次のような考え方でした。
設計書は完璧にはならない。最後に残る「事実」はコードだけ。
それまでの私は、
- 設計書が「正」で、コードはそれに従うもの
くらいに思っていました。
でも、詳細設計がほとんどない現場に放り込まれてみると、実感としてはむしろ逆でした。
- 設計書は更新されず、すぐ古くなる
- 設計者が異動や退職でいなくなると、意図が分からなくなる
- 最後まで頼りになるのは、結局コードだけ
「じゃあ、自分が書くコードは、そのまま残る設計書として読まれるんだよな？」
そう考えた瞬間、「コードは設計書だ」という言葉が、他人のきれいごとではなく、自分の責任にそのまま乗ってくる感じがしました。
まず変えたのは「名前でごまかさない」こと
いきなり大きな設計を変えるのは無理なので、私が最初に手を付けたのは、いちばん身近なところでした。
変数・メソッド・クラスの名前を、とにかくちゃんと考える
という一点です。
やってみると、思った以上に名前で詰まります。
- 「〜Manager」「〜Helper」のような、曖昧な名前に逃げたくなる
- 1メソッドでいろいろやりすぎていて、うまく説明できない
つまり、
名前が決まらない = 責務がはっきりしていないサイン
だと分かってきました。
そこで、名前に詰まったときは「設計を見直すタイミング」だと決めて、次のようなサイクルを回すようにしました。
- 処理をもう少し細かく分けてみる
- それぞれに「自信を持って言える名前」を付けてみる
- それでもモヤモヤするなら、さらに分割するか、役割を変えてみる
完璧からは程遠いですが、「設計書どおりに書けばいいや」という受け身のスタイルからは、一歩抜け出せた感覚がありました。
JavaDocを「第二の設計書」にする
もう一つ意識して変えたのが、JavaDoc の扱いです。
それまでは、
- 形式的に埋めるだけ
- メソッド名をただ言い換えただけの説明を書く
くらいの扱いでした。
しかし、設計書が薄い現場で作業するうちに、
設計書が頼りにならないなら、コード側で意図をしっかり説明するしかない
と考えるようになりました。
それからは JavaDoc を書くときに、次のような点を意識するようにしました。
- 何をするメソッドなのか
- なぜこの仕様なのか（背景や制約があれば一言でも書く）
- 呼び出し側は何を期待してよいのか
「こう動きます」という事実だけでなく、「なぜそうしているのか」という理由も、可能な範囲で残しておくようにしたのです。
設計書が完璧ではない前提で、
JavaDoc を「第二の設計書」にする
という位置づけを、自分の中で決めた感じでした。
それでも、まだ全然できていない
もちろん、今の自分が理想的なコードを書けているわけではありません。
- 「もっときれいにできるはず」と思いながらも
- 改善方法の知識や経験が足りず
- スケジュールとの兼ね合いで、やむなく妥協する
という場面は、正直なところまだたくさんあります。
それでも、最低限ここだけは意識しています。
- 処理をできるだけ細かく分ける
- 名前とコメントで「意図」が伝わるようにしておく
完璧な設計はできなくても、
後から読んだ人が「何をしたかったか」だけは分かる状態
を目指す。今のところ、それが自分なりの「コードは設計書だ」との付き合い方です。
同じようにモヤモヤしている人へ
たいした肩書きがあるわけでもない、ごく普通の実装者としての実感ですが、
- 詳細設計がない現場で迷子になったことがある人
- 設計書とコードのズレに、なんとなくモヤモヤしている人
には、「コードのほうを設計書だと思って書いてみる」という視点は、けっこう効き目があるんじゃないかと思います。
大きなことをやろうとしなくても、まずは
- 名前でごまかさない
- JavaDoc やコメントで、最低限の「意図」を残す
このあたりから始めるだけでも、少なくとも「未来の自分」が読むときのストレスは、かなり減ります。