「クロワッサンのレシピ」と「ダメなソースコードコメント」

「クロワッサンのレシピ」と「ダメなソースコードコメント」

突然ではあるが、クロワッサン（あるいはパイ、ブリオッシュなど）の作り方をご存知だろうか？作る途中で小麦粉を練った生地を四角に広げ、その上に生地の半分くらいの面積に薄く広げたバターを重ねてそこからさらに折り紙を折るように生地を重ねてバターを包み、その後何度か折っていく過程があるのだが、ある日見ていた食文化専門チャンネルのレシピ番組で紹介していたその工程の映像を見ていて私(パンは素人)はなんでそんな風にバターを混ぜるのかがわからなかった。ただバターをそう言う風にして生地に織り込んでいると言う事実だけをナレーションと映像から感じ取っていた。

そしてその理由を妻に聞いてみると疑問はあっさり解決。この工程が無いとクロワッサンではなくなると言う事らしい。つまり、上記のとおりに作ると最終的に生地は以下のような感じになる

小麦粉の生地
バター
小麦粉の生地
バター
・・・以下何層か続く・・・
バター
小麦粉の生地

このようにしたうえで正しい手順で成形して焼くと途中でバターが溶けて流れ、その部分が空洞になる。空洞が出来てさらにその空洞のおかげで小麦粉の生地全体に熱がしっかり入り、結果としてクロワッサンやパイ特有のあのサクッっとした食感が生まれると言う事だった。なるほど！納得した。

伝わりにくいかもしれないのでレシピのページをいくつかご案内
http://www001.upp.so-net.ne.jp/e-pan/croissant/croissant-1.htm
http://cookpad.com/recipe/278247/

さて、上記を踏まえてようやく本題。
ここでとあるRDBMSを使ったシステムのソースコードがあったとする。

// ほげデータの作成処理
HogeData hogeData = new HogeData();
hogeData.setHoge1( aaa );
hogeData.setHoge2( bbb );
・・・
hogeData.setHogen( nnn );

// 作成したデータを使用してテーブルにINSERT
insertHoge( hogeData );

// ここでほげほげ情報を最新に更新・・・(*)
updateHogeInfo( 何かの引数 );

for( int i = 0; i < meisaiCount; i++ ){
    // さっきINSERTしたデータの明細に当たるデータの作成処理
    HogeDataDetail hogeDataDetail = new HogeDataDetail();
    hogeDataDetail.setHogeDetail1( aa[i] );
    hogeDataDetail.setHogeDetail2( bb[i] );
    ・・・
    hogeDataDetail.setHogeDetailm( mm[i] );

    // 作成した明細データをテーブルにINSERT
    insertHogeDetail( hogeDataDetail );
}

私はこのソースコードをその詳しい業務仕様を良く知らずに(と言うか実は資料がほとんど無いのでコードを読まざるを得なかったのであるが･･･)読んで、疑問に思ったのが(*)の部分の更新処理である。何かのデータを更新しているのは分かる。
コメントにもそう書いてある。しかし、何でかがわからない。あるデータを登録して、そのデータの明細を登録する間にどういった理由でそのデータを更新する必要があるのだろう？これはまさにクロワッサンのレシピを見ていて思った疑問と同じだ。

このコードを書いたプログラマはなんとなしに(*)のコメントを書いたのかもしれないが、残念ながら私には何も伝わらなかった。コメントを書く理由として重要なものの中に「（数週間後の自分、または自分以外の誰かがいつか行うであろう）将来のメンテナンスの為」と言うのがあるが、このプログラマは残念ながらそう言う意識を先輩から教えてもらえなかったようであるこれではむしろコメントなんか無いほうがマシとさえ言える。

んで、これを読み解くには結局前後のコードを完全解析するか、想像力を働かせるか、他にこのコードに携わった人をなんとか捕まえて聞くしかないわけである。こんなのがソースコードのあちこちにあってしかも設計書が全くもって無いシステムのメンテナンスを任せられたらどんな気分だろう？

ただ一言、こんな感じで書いてあれば良いだけなのに･･･

// 明細登録前にこの情報を最新にしておかないと明細登録処理時に
// ・・・となってしまい、正しく登録できないのでここで更新
updateHogeInfo( 何かの引数 );

とまぁ、冒頭のTV番組を見ていて思った事とイメージがダブったのでこんなエントリを書いてみたわけである。

その時見ていたTV番組でもナレーションで「なんでバターをこんな風に織り込むのか？」を説明してくれれば良かったのだが残念ながらそのような説明は無かったのである（あるいは私が聞き漏らしていただけかもしれないが･･･）。

まぁ、パンのレシピなら忠実にそれを守れば理由は知らずともおいしいパンは食べられるだろうが、プログラムのメンテナンスとなればそうはいかない。かと言ってこんな所で時間を無駄にするより、次々登場する新しい技術を追いかけていた方が人生楽しいと私は思う。

と言うことで今回の内容は特にプログラマの部下を持っている（今後持つであろう）皆さんにささげたい。自分はともかく後世にコメントのあるべき姿を伝えていくのはあなたしかいないのである。

最後のくだりはある意味ホント。コメントのあるべき姿なんて大学や専門学校でなんてまず教えないと思うし、事実としてある程度の規模をもった業務系システムのプロジェクトでも経験しない限り、たとえ学校で教わったとしてもその意味合いが伝わらないので全然身に付かないのがオチ。まぁ、自分の作ったシステムをそのシステムの寿命が来る最後まで自分で全部面倒見るなら別にこんな事意識し無くてもいいっちゃぁいいんだけど。

え、「そもそも仕様書やら資料が存在していない事自体がおかしいのでは？」だって？まぁ確かにそうですね。それについてはまたの機会にお話できればと思います。珍しくながーいエントリでした。