steps phantasien
最近嬉しかったこと
昔の同僚が退社してベンチャー仕事をやるという.
門出を祝う宴会に, 昔のよしみで呼んでもらった. ついでに古巣の近況を聞く.
ひとつ嬉しい知らせがあった. 以下その自慢話.
ある夏, 私は社内ライブラリのチュートリアルを書いた.
そのチュートリアルが, 今でも改訂されながら参照されているという.
のみならず新人プログラマの研修教材として広くとりいれられつつあるそうだ.
私はとても嬉しくなった.
もちろん手柄は改訂を続け, 様々な改善を続けた彼らのものだ.
それでもなお私は喜びを隠せない. 自分が去った今も文章だけが生き続けている.
私は平凡なプログラマだから, 自分のコードが生き残れるとは思えない.
一方ボランティアで仕事の合間に書いた文章は読み継がれている.
価値のあるものが生き残るのなら, 私のなした価値は(コードではなく)文書にあったことにある.
プログラマとしては悲しいけれど, 会社員としては嬉しい.
グラスのビールをあおりながらその頃のことを思った.
あるチュートリアルの思い出
![]()
Building Application Frameworks では
フレームワークの文書を以下のように分類している.
●サンプル (Example)
●レシピとクックブック (Recipes and cookbooks)
●契約 (Contracts)
●デザインパターン (Design patterns)
●概要 (Framework overview)
●リファレンスマニュアル (Reference manual)
●設計ノート (Design notebook)
当時, 社内には古い設計ノートが少しと断片的で古いリファレンスマニュアルがあった.
概要を説明するスライドもあった気がする.
契約とかデザインパターン云々はライブラリだとあまり関係ない.
一方で, 自分が新しいコードベースを使う時に参照するものは何かと考えてみる.
まずサンプルを見るだろう.
次に適当な空プロジェクトを作りサンプルのコードをいじりながらコピーする.
それで動けば OK. 適当なサンプルがない時は
ウェブや添付の文書を調べて目的のコード断片を探す.
結局欲しいのはコードだ.
みつけたコードの意味がわからないと, ようやく文章に目を通す.
前後の説明を読むかもしれない. リファレンスを引くかもしれない.
議論を重ねた同僚と私も同じ結論になった. コードが必要なのにコードがない.
上の分類でいくと, 一番欲しいのはサンプルで次がレシピ. そういうのを作ろう.
一見必要そうなリファレンスマニュアルだが, 社内のライブラリならコードを読めばいい.
MSDN とは立場が違う.
私には﹃文書を書くのに挫折しない﹄という目標があった.
かつて私は同じライブラリのリファレンス作成に挑戦するも挫け, かなりの労力を無駄にしていた.
また社内には同じように書きかけで放置された文書が散在していた.
一方の同僚は﹃大半の文書は読まれない﹄と主張していた. これも事実だった.
社内には色々な PDF があったが, 私はほとんど読んでいなかった.
読まれる文書を, 挫けない範囲で書こう.
そのためにはライブラリの最頻イディオムをサンプルつきクックブックとしてまとめよう.
そう考えた.
社内にはそのライブラリで作られたアプリケーションが色々あり,
ライブラリを使う時はその中から欲しいコード片を掘り起こすのが常だった.
苦労の多い作業だった. オブジェクトの初期化, 設定, 利用のシーケンスは
コード内に分散しており, それを漏れなく抜き出すのは難しい.
コードの質も玉石混合で, バグを持ったままコピペされることもあった.
私達の目的は, 極端に言えば便利で正しいコピペ素材を提供することだった.
チュートリアルは Wiki に書き, フィードバックをうけて改良した.
(その時に私は初めて自分のコードがいくつかの
コンベンションに違反していることを知ったのだった...)
対応するサンプルコードはパッケージしてトップページに添付した.
コードはビルドできる範囲の最小構成にするよう留めた.
そのライブラリは巨大なフレームワークの一部だったので,
最小限の構成を作るのには意味があった.
フレームワークを使ったビルド可能なアプリケーションは多くあったけれど,
サンプルとして動かすには大きすぎた. 試したいコードパスを通すだけで一苦労.
書いたコードを短い反復で試すことはできなかった.
サンプルのプロジェクトは main() から追いかけることができるよう,
フレームワークの皮を剥がして直線的な構成にした.
xUnit を組込みたい誘惑にも駆られたが素朴さをとった.
文書の読者は同僚, 特に後輩や新入社員に的を絞っていた.
各章の章末には練習問題をつけ, 実際に手を動かせるようにした.
配属された新人にこの文書を渡し, 勝手に自習させるのが当初の目的だった.
しかしこの目論みは外れた. 他に少しでも仕事があると自習なんてしない.
チュートリアルには目を通してもサンプルを動かす人は少なかった.
そこでかわりに締切を決めて提出を求め, 解答のコードをレビューすることにした.
自習よりレビューの方がずっと効果は大きかった.
実アプリケーションのコードを汚すことなく,
新人にありがちな失敗(エラーチェック漏れ, コンベンション違反など)を
正していくことができた. 手を動かすのは思ったより大事なのだった.
新人にとっても, 巨大なコードを前に途方に暮れて過ごす
無為な時間が減ったのは幸いだったと思いたい.
文書が必要な場所
はー. こうしてみると当時は色々考えて書いたんだなあ...
自慢話につき尾鰭は間引いてくださいね.
それからもしばらくプログラマをしてきたけれど,
気合を入れて文書を書いた記憶はない.
たぶん大きなチームで開発をしていないからだと思う.
小さいチームなら, わからないことは書いた当人に聞けばいい.
コードの規模もたかが知れている.
なんとか俯瞰できる規模のコードを小さいチームで書く.
工学的な挑戦はないけれど, そんな小気味良さが好きだ.
百人のチームで数百万行のコードを書く大規模開発も一度くらいはやってみたい.
でも色々な塩梅を考えると私がその道を選ぶことはもう無いだろう.
最近はそんな気がしている.