ドキュメント，書いてますか？
ドキュメントというものを初めて意識した日のことは明確に覚えている。いや、年月日は覚えてないけど。大学のコンピュータクラブの先輩の Kさん（もちろん当時学生）が書いたドキュメントを見た日である。多分1990年ごろのこと。
Kさんが書いたX68000用の独自のウィンドウシステム Ko-Window（何を言っているのか分からない人が大多数だと思うが、本題とは関係ないので無視してください） のプログラマ向けマニュアルのようなものだったと記憶しているが、とにかく読んで衝撃を受けた。
ぴったりくる表現がなかなか見つからないが、なんというか、文章が「かっこいい」かつ「気持ちいい」のである。飾り気もないプレーンテキストで、ただプログラムの説明が書いてあるだけなのに、読んでいて楽しいし、ある種の感動もあった。
Kさんは凄腕プログラマである。私の出会った中でトップのプログラマだと思う。現在も現役でプログラマーをやっていらっしゃるが、その技術力の高さは私は今も遠く及ばない。
Kさんの凄さを物語る数々のエピソードがある。脱線になるが、一つ紹介してみよう。
Kさんはいつも自分で書いたエディタでコーディングしていた。そう、自作のフルスクリーンエディタである。当時はMS-DOSが普及し始めた段階で、Windowsのような統一的なOSは普及しておらず、パソコンの機種毎にソフトを作らねばならなかった。
当然エディタも機種毎に用意せねばならない。既製品のエディタもあったが、自分が使いたいパソコン用のバージョンがすぐに提供されないこともよくあった（統一OSがないので、ある機種で動いているソフトを別の機種で動かそうとすると「移植」という修正作業が必要だったのである）。
そういう状況だったので、Kさんはいつでも使える自分専用のエディタが欲しかったのだと思う。Kさんは C言語で書いたこのエディタのソースをいつもフロッピーディスクに入れて持ち歩いていて、新しい機種のパソコンを使うことになるたび（＊１）に、下回りのドライバー層を新機種に適応させることで移植していた。
（＊１：当時はバブル期だったこともあり、やり手の先輩が交渉していろんなメーカーさんから大学のクラブに何種類もパソコンをタダで提供してもらっていた。）
移植に要する期間はだいたい数日だったと思う。アーキテクチャが異なる機種間の本格ソフト移植が数日！である！。並のソフト開発業者に見積らせたら、何人月で出てきただろうか、とうぐらいの凄いことを、Kさんはさらっとやってのけていた。
そんな凄いことができるのは、Kさんが作るソフトの設計の見事さが大きな理由だった。また、その設計力は、Kさんの文章力＝言語能力の高さと強い相関があると思う。
私が衝撃を受けたKo-Windowのマニュアルも、Kさんの素晴らしい設計力と文章力が遺憾なく発揮されていた。簡潔に理路整然と設計や使い方が説明されていただけでなく、Ko-Windowで何をやりたいのかという設計者としての構想や意思がひしひしと伝わってくるものだった。
これを読んで以来、私は「良いプログラムを作りたい」というのと同じぐらい「Kさんのような素晴らしいドキュメントを書けるプログラマになりたい」という憧れを抱くようになった。「優れたプログラマは、良いコードだけでなく良いドキュメントを書けるものだ」という価値基準が自分の中に生まれたのだ。
ところで、職業プログラマーのみなさんの中には、ソフト開発にまつわるドキュメントというと「プロジェクトの最後のほうで納品のために仕方なく書くもので、ただただ面倒な存在だ」と思っている人もいるかもしれない。
DBのテーブル定義をただ展開しただけで何の説明もないエクセルシートとか、画面のスクリーンショットがひたすら貼り付けてあるだけのワードファイルとか。確かに私も単に形式を満たすためだけの無味乾燥としたドキュメント作成は苦手である。今では様々な優れたツールやChatGPTがあるので、そうしたドキュメントは90%以上自動生成できると思うし、そうすべきだ。
私が書くことをおすすめしたいドキュメントは、そういうコーディングが終わってから書くドキュメントではなく、コーディング前に書くドキュメントである。現在ではこのドキュメントに丁度よい名前がある。「デザイン・ドック(Design Doc)」である。
デザイン・ドックの主旨や詳しい書き方は、昔アットマークITに寄稿した記事があるのでそちらを見て欲しいが、その発想はシンプルである。これから作ろうとするプログラムの構想や基本設計を設計者視点でまとめた文書、それだけである。
フォーマットも自由だし、どれくらい細かく書くかもその時の必要性に応じて決めればよい。要点をまとめれば良いので、カッチリと形式ばって書く必要もない。
なぜデザイン・ドックを最初に書くべきのか？ 第一の利点として自分の設計に何か問題ながいかを自分でチェックできるということがある。
プログラム設計を頭の中で「理解した！」とか「見えた！」と思っても、よほどの天才でもない限り、大概は何かしら見落としや矛盾があるものだ。その証拠にその内容を文字に書き起こしてみると、案外スラスラ書けないことに気づくだろう。
これこそがデザイン・ドックを書くことの大きなメリットである。自分が正確に理解できてないことは文書に書けないので、書こうとすることでそのことに気づけるのである。
第二の利点としては、他の人に設計の「大きな意図(Big Picture)」を伝える文書として使えるということ。物理的な実体をもたないソフトウェアの設計思想や背景はそもそも他人に伝えにくい。
コードの中のコメントがあるとしても、粒度が小さすぎて大きな全体像は表現されていないことがほとんである。やはりそうした全体感を説明するには一つのまとまった文章として表現するほうが適している。
第三の利点は、コーディング前に書くほうが楽しい・モチベーションが上がるという点。上に書いたようにソフトの完成後にドキュメントを書くのは、すでにプログラマとしての「結論」が出ていることを思い出していく作業なので、退屈になりがちである。
それよりもコーディング前にこれからどんなものを作ってやろう、どんな技術をつかおう？と、色々と構想を巡らせながら書いたほうが遥かに熱が入るし、私はそのほうがワクワクすると思う。
このように色々なメリットがあるデザイン・ドックなので、プログラマのみなさんには是非書くことを習慣づけてほしい。実際、一度でも書いてみるとメリットを実感するので、手放せなくなるはずだ。
今回書きたかった話は以上です。お付き合いありがとうございました。
株式会社オープンストリームのご案内
コーポレートサイト
https://www.opst.co.jp/
Keep Innovating! Blog（公式ブログ）
https://www.opst.co.jp/keep_innovating_blog/
サービス、ソリューションに関するお問い合わせ
https://www.opst.co.jp/contact/c_service/
採用サイト
https://recruit.opst.co.jp/