誰でも読めないとダメ？
かつて、ドキュメントを書く際に上司によく言われたものである。
「誰が読んでもわかるように書きなさい」
当時はなるほど、そうしないと、と思ったが、今はこんなの時間の無駄だと思っている。
ソフトウェアの詳細設計書を非エンジニアでも読めるように書く、というのは時間の無駄でしかない。例えば、スーパーのレジ打ちのおばちゃんにも読めるような設計書を作ることに意義があるとは到底思えない。*1
もっとも、上司は「誰でも」という言葉にそんな極端な例を含めてはいないだろう。しかし、きっと新人エンジニアや対象技術ドメインにうとい人は含まれている。だが、そうした人々向けにドキュメントを書くことはやはり無駄であると思う。初心者向け資料は熟練者には冗長すぎて読みづらいものだ。まだ戦力になり得るかわからない人のために、現在高い生産力をたたき出しているエンジニアを不自由にさせるべきではない。*2それに、冗長な情報が多く含まれるということはドキュメントのボリュームがふくらむということで、作成するにも読むにもコストがかかりすぎてしまう。
問題はそもそもそんな戦力外の人間が配属されること、および配属してから戦力になるための教育を与えられない点にあり、手を入れるべきは人事と教育システムである。現場でエンジニアがくどいドキュメントを書くことで対応するのはおかしい。
なぜこんなことを唐突に書き出したかというと、2008-01-11 - yvsu pron. yas中のある記述を見て気になったからである。
スクリプト言語のソースが読みにくいと書いているつもりはありません。他の人の書いたソースを追いかけていくときに、型情報があったほうが、情報が多い分追っかけやすいということです。
そろろろRailsについて本音を書いてみるか - yvsu pron. yas
（略）
やっぱJavaの方がソースコードが多いジャンと思われる方もいると思いますが、今のSeasar2は規約は最小限にして後から見た人のために、ソースを追うための必要な情報を残すようにしています。この辺は、ポリシーの違いですね。
俺のブクマコメおよび記事への言及ありがとうございます。俺だけを相手にしているわけじゃないでしょうが。
それはともかく、これに似た意見は方々で見られる。当該記事で議論の対象となっているRuby on Railsは、Rubyという動的型言語で実装されている上、"CoC"(設定より規約)というポリシーに則った設計が為されているため、世のFW（フレームワーク）ではコードか設定ファイルに現れる情報の多くが暗黙知になっている。だから、それを知らない人間がコードを読むには手がかりが不足するのではないか、それが保守性低下を招くのでは、というのである。
かつて例に出したコードだが・・・。
def edit @person = Person.find(params[:id]) end
Ruby on Railsを知る人間にとっては、このコードがどことどう連携するのか一目瞭然なのだが、知らない人が見ればわけがわからないであろう。Personがapp/models/person.rbに定義されていること、paramsの中身、実行後app/views/person/edit.html.erbが描画されること、などなどはコードや設定ファイルに現れない。だから、知らない人がコードを見たときに、何をやってるかわかりづらいというのはその通りだと思う。
しかし、知らない人がコードを読むことを前提とすべきなんだろうか？俺ならまずRailsを学習させ、現在作成しているアプリケーションの設計を教え、扱いを理解した上で初めてコードを触らせる。人の書いたコードを読む場合でも、それがFWに乗ったものであれば、それの理解から始める。それはどんなツール、どんなFWを使っていても同じだと思う。
言及記事は、どうやら対象コード（というかアーキテクチャ？）への理解が浅い人でも読めるようにしておいたほうが良い、と言っているように思えるのだが、それは先に挙げたドキュメントの例同様、問題の認識と対処すべき場所を間違っているように思える。知識を持たない人間の相手は、コードがすべきことじゃない。
そもそも、Seaser2やStruts+Springに型情報があるから、設定ファイルに必要な情報が書かれているからといって、コードさえ読めばそのふるまいを的確に理解できるのだろうか？結局そのFWのアーキテクチャや作法などをちゃんと理解しておかなければ、本当に把握することはできないのではないか。むしろ、型情報なんてものがあるがためにコードを部分的にしか読まず、それでちゃんと把握できたように錯覚し、半端な知識でコードをいじってしまう危険性もあるのではないか、という懸念もある。
結局コードを読む前にしっかりとした前準備、つまり言語の理解、FWの理解、設計の理解を踏まえるべきであり、そうする限りFWがなんだろうが、型情報があろうがなかろうがコードの読みやすさ、保守性の高さには大した差が無い。踏まえないというのは体制かそのエンジニアの意識の問題であって、コードの問題ではない。規約を減らしてコードに型情報を書く、といったお茶を濁すような対処をするよりは、前準備および人選にリソースを割くべき。
そう思うのだが、どうか。
