2008年03月10日(月)

ドキュメント内のリテラルにも注意

テーマ:設計

アプリケーション開発では、「なんとか区分」とか「なんとかステータス」などといったデータを扱うことがよくある。例えば、

承認ステータス: 0=申請中, 1=承認済, 2=差戻し

というように、決まった値を持つようなもの(名義尺度や順序尺度 )である。

プログラミングでこうした値を扱う場合は、数値やコード値をそのまま(リテラル )では記述せず、定数を定義して、それを使う。あるいは、「列挙型 」を扱える言語であれば、そちらを使う。


ソースコードが読みやすくなるのはもちろん、数字と「意味」の対応が変わった時に、定義だけを変えれば対応できるからだ。例えば、途中に新しいステータスが挿入されて後ろの数字がずれたとしても、既存のソースコードには影響しない(もちろん、挿入したステータスを使う必要がある箇所は別だし、新しいステータスの追加により「意味」が微妙に変わったりすると、修正が必要にはなるが)。


これはプログラマにとっては基本的なテクニックであり、初心者の書いたコードでもそうなっていることがほとんどだろう。



しかし、どういうわけか、設計書等のドキュメントでは、数字がそのまま書いてあるようなものをよく見かける。

承認ステータスが 2 のデータを検索する

といった具合である。これではどんなデータを検索しているのか、直感的に分からない。別途、ステータスの意味が冒頭のように定義されているのなら、

承認ステータスが「差戻し」のデータを検索する

でよいだろう。何らかの理由で数字を直接書くというルール(文化)だったとしても、

承認ステータスが 2(差戻し) のデータを検索する

という具合に、補足的に「意味」を書いた方がよい。


ドキュメントに数字を直接書くと、後から値の意味が変わった場合に、修正箇所が非常に大きくなる。しかも、可読性が悪いため、修正ミスに繋がりやすい。そのあたりの事情はソースコードと全く同じである。


通常、こうした数字の変更は、単純に置換すればよい、というわけにはいかない(そもそも、数字だと、関係ない色々な箇所がマッチするので、検索しにくいという問題もある)。例えば、上記の定義が、

承認ステータス: 0=申請中, 1=課長承認済, 2=部長承認済, 3=差戻し

に変更になったとしよう。

この場合、「2」を「3」に変更するという他に、「1」を「2」に変更するケースもあるだろう。これを無計画に数字だけを見てやっていると、変更途中のある時点での「2」が、元々「2」だったのか、元は「1」だったものが「2」に修正された結果なのか分からなくなる。つまり、元々「1」だったものを誤って「3」にしてしまう危険性が出てくる。実際には、「1」については、「2」にするという変更以外にも、「1」のまま修正しない、「1 または 2」にする、「1 かつ 2」にするなど、複数の修正パターンが発生するため、混乱しやすい。


・・・と、この文章も既に何を書いているのか分からなくなってきている。これ自体、数字による表記がいかに分かりにくいか、ということを示している。


このような変更が発生した場合、数字ではなく「意味」で記述している場合も、修正が全く不要になるわけではない。しかし、少なくとも「差戻し」については変更不要である(※)。「承認済」についても、「課長」や「部長」の文字がなければ、未修正であることが一目瞭然なので、修正が漏れにくい(ソースコードで、定数名の定義を変更してコンパイルエラーを発生させるのと同様である)。


数字と「意味」を併記する方法では、修正箇所が少なくなるわけではないが、数字だけの場合に比べると、やはり修正箇所を見つけやすい。また、修正漏れがあっても、定義と一致しない記述が残ることになるので、後から見たときに発見しやすいというメリットもある。



仕様変更に対する対応が大変なのは、ソースコードもドキュメントも同じである。むしろ、ソースコードの方が、開発ツール等が充実している分、簡単かつ安全に修正できるのではないだろうか。ドキュメントを記述する際には、プログラミング以上に、将来の修正に対する配慮があってもよいだろう。






※「承認済」という表現を「課長承認済 かつ 部長承認済」と再定義してしまうことで、修正範囲をもう少し減らせる可能性はある。ただし、その場合は、「承認済」という記述が残っていれば「未修正箇所」である、という短絡的な判断ができなくなるため、得策ではないかもしれない。





■関連記事
YYYY/MM/DD
この文書は誰が読むのか
どこまで書くか設計書
資料の画像は減色せよ




SEの文章術 [技評SE新書] (技評SE新書 10)
克元 亮
技術評論社 (2007/05/03)
売り上げランキング: 14515
おすすめ度の平均: 5.0
5 文章力に不安のあるSEの方は必読です。
5 SEであるか否かを問わず自分のドキュメントを最適化していく為に好適な良書

90分で学べるSEの文書技術 (ITプロフェッショナルの基礎知識)
高橋 慈子
日経BP社 (2005/06/02)
売り上げランキング: 61805
おすすめ度の平均: 3.5
3 自分の文章を見直すきっかけになるかも
2 ラブソン歌ってる
5 日頃の仕事のシーンに役立つ一冊!

AD
いいね!した人  |  コメント(3)  |  リブログ(0)
2007年02月12日(月)

設計が過去に引きずられる

テーマ:設計
最近、古いクライアント・サーバー(C/S)型のシステムを、Web システムとして作り変えるという仕事が多い。現在の機能をそのままに、Web ブラウザから使えるようにしてくれ、という依頼である。

こういった場合に注意すべきは、新しいシステムの設計が既存のシステムの設計に「引きずられてしまう」ことである。この問題は、特にユーザー・インターフェースについて顕著だ。既存のシステムを使い慣れたユーザーからは、「今と同じ使い勝手にしてくれ」という注文がなされる。また、設計者の中にも、既存のシステムとなるべく同じ設計しようとする人がいる。そのほうが全く新しい「画面」を設計するよりも、楽だからだ。


しかし、プラットフォームが違えば、一般的な操作性も変わる。C/S で使われているファットクライアントな設計が、必ずしも Web システムで使いやすいとは限らない。むしろ、従来の設計をそのまま Web に持ち込むと、不自然な操作性になってしまうことも多い。既存のユーザーは満足するかもしれないが、新しいユーザーにとっては、むしろ使いにくく感じられるだろう。

また、この「不自然な設計」は、一般的に、実装(プログラミング)の手間を増やす。C/S では簡単にできていたことが Web ブラウザでは実現できない、ということも多く、リッチクライアントと称されるような拡張的な技術(例えば Ajax や Flex のような)を導入せざるをえないからだ。最近では、そうした技術もかなり普及し、開発効率もよくなってはいるが、それを使わない場合よりも工数が増加することには変わりない。


このように、システムを全面的に作り直す際には、旧システムの設計を単純に流用するのではなく、いったん、要件定義まで立ち返って考え直すべきだろう。

旧システムを参考にする場合も、その構造がどうなっているかということよりも、旧システムが作られた理由、即ち、そのシステムが解決すべき問題が何であるかということに注目すべきだ。そして、その問題を解決するためのシステムを新しいプラットフォームで作ったらどうなるか、ということを改めて考えるのである。

つまり、それは全く新規のシステムを作るのと同じことである。システム開発者にとって、何も特別なことではないだろう。しかし、旧システムが存在しているとなると、どうしても、人はそれに引きずられてしまいそうになる。そういう意味では、全く新しいシステムを作るよりも、既存のシステムを作り変えることのほうが難しいことなのかもしれない。





■関連記事
一般的な使い方
気の利いたプログラムは顧客満足度を上げ、開発工数を下げる
想定外の使われ方



C/Sシステムの設計・構築―3階層型、Web系にいたるC/S開発のすべて
藤沼 彰久 斎藤 直樹 野間 克司 小川 義明 並河 英二 沼田 薫
日経BP社
売り上げランキング: 461853


Web系の仕事―システムエンジニア篇
友重 卓司
同友館
売り上げランキング: 459653
おすすめ度の平均: 5.0
5 とにかく読みやすい

AD
いいね!した人  |  コメント(5)  |  リブログ(0)
2006年06月11日(日)

YAGNI ~ 予想でモノを作るな

テーマ:設計
人間には未来の出来事を知ることはできない。だから、せめてできる限りの予想をして未来に備えよう、ということになる。プログラマの仕事でもそうだ。

「次のバージョンアップでこんな機能が要求されてるんだけど」
「そんなこともあろうかと、その仕組みは既に作ってあります」

なんてことになれば、得意な気分になる。予想が当たれば嬉しいのは、ギャンブルもソフトウェア開発も同じだ。


しかし、予想に基づく行動にはリスクが伴う。それもギャンブルと同じである。

以前、私は、あるシステムの内部データを CSV ファイルとして出力するプログラムを作った。その際、将来のバージョンアップで出力するデータ項目が追加されるかもしれないと考えた。そこで、プログラムを直さなくても、「定義ファイル」に項目を追加するだけで、CSV に出力できるようにしておいた(顧客からそんな要望はなかったにも関わらずだ)。

しかしである。その後、実際に追加された出力項目は、どれも定義ファイルでは対応できないものばかりだった。今までにない計算が必要なものだったり、全く別のデータの参照が必要なものだったり・・・。結局、プログラムを変更して対応せざるをえなかった。そして、最初に定義ファイルを利用するために作ったソースコードの構造は、中途半端で邪魔な負の遺産として残ることになった。

このように、予測に基づくプログラミングにはリスクが伴う。予想が外れれば、先行投資した時間が無駄になるばかりか、ソースコードが無駄に複雑化し、以後のメンテナンスにも影響を与えるのである。


XP(エクストリーム・プログラミング)には、YAGNI という言葉がある。「You Aren't Going to Need It.」の略で、直訳すれば「あなたはそれを必要とするようにはならないだろう」。意訳すれば「そんなものいらないだろう」ということだ。つまり、「予想でモノを作るな」、「今必要な機能だけを作れ」ということである。

本当に必要な機能だけを作れば、プログラムの構造はシンプルになる。シンプルなプログラムには機能追加も楽にできるのだから、将来、別の機能が求められれば、そのときに作ればいいというわけである。


これは簡単なことのように見えるが、実は難しい。技術的に難しいのではなく、心理的に難しいのだ。特に、経験を積んだ技術者ほど、そう感じるのではないだろうか。プログラマというものは、多少の労力を払ってでも「拡張性」や「汎用性」が高く、気の利いた機能 を持ったプログラムを作りたいと考えるからだ。

もちろん、そうした、いわば「理想的な」プログラムを目指すということも大切である。YAGNI を絶対視し、常にシンプルさを最優先すればよいというものでもないだろう。結局のところ、そのシステムの特徴や顧客の特徴、開発プロジェクトの状況などを踏まえ、適切なバランスを考えることが重要だろうと思う(※)。

それでも YAGNI という言葉にとても価値があると思うのは、ともすれば理想に走りがちな開発者に現実的なバランス感覚を与えてくれるからである。設計を始めるとき、あるいは設計に迷ったとき、思い出したい言葉である。

応援のクリックお願いします →



※言うまでもないが、「理想的なプログラムを作れるが、あえて作らない」ということと、「理想的なプログラムが作れない」ということは違う。また、「理想的なプログラムを開発すること」と、「理想的なプログラム開発」も違う。



■関連記事
気の利いたプログラムは顧客満足度を上げ、開発工数を下げる



XPエクストリームプログラミング懐疑編―XPはソフトウェア開発の救世主たりえるのか
ピート マクブリーン
ピアソンエデュケーション (2002/12)
売り上げランキング: 271,315
おすすめ度の平均: 4.5
4 「自ら考える」ための一冊 (決して XP をけなす本ではない)
5 宗教論争に待った!をかけてる?


ペアプログラミング―エンジニアとしての指南書
ローリー ウィリアムズ ロバート ケスラー
ピアソンエデュケーション (2003/03)
売り上げランキング: 61,747
おすすめ度の平均: 4
4 上司説得のための武器に
5 開発するにあたって
4 ペアプログラミングを包括した解説書
AD
いいね!した人  |  コメント(5)  |  リブログ(0)
2006年03月25日(土)

嘘つきのはじまり

テーマ:設計
世間の人々は、コンピュータシステムがどのように動くかということは、きちんと文書にまとめられているものと思っているかもしれない。プログラムは、仕様書を元に寸分違わず作り上げられるものだろうと。「コンピュータ」とか「プログラム」という言葉には、そのようなキッチリとしたイメージがある。

しかし、実際には全くそんなことはない。仕様書(設計書)が全く書かれない場合もあるし、書かれていても「嘘」であることも多い。プログラマに設計書とソースコードを渡して、そのプログラムがどのような動作をするか尋ねてみるといい。そのとき、「確実な答えが欲しい」と念を押せば、彼は必ずソースコードを読むだろう。


もちろん、設計書に最初から嘘が書かれているわけではない。システムを作っているうちに、実際のプログラムと一致しなくなってしまうのである。システム開発では、設計後に仕様変更が発生したり、想定外の問題に直面して実装方法を変更したりすることは日常茶飯事だが、そのときに設計書を修正しないからだ。

なぜ修正しないかって? そのための時間が足りないからである(つまり費用や納期の問題である)。以前に、「システム屋はテストを削る 」と書いたが、「ドキュメントの修正」も削られることは多い。

プログラムが出来たら設計書は捨ててしまえばよいと思われるかもしれない。ロケット打ち上げ時のエンジンのように、開発が軌道に乗ったら切り離してしまうわけである。それなら修正する必要もない。

しかし、設計書はシステムの開発に使われるだけではなく、ユーザーの受け入れテストや、その後の保守や改訂にも利用される。「納品物」になっていれば、捨ててしまうわけにもいかない。

そんなわけで、システム開発工程の最後に「ドキュメント整理」などというフェーズを作って、後から設計書を直すようなこともある。


仕様をドキュメントに書けば、ソースコードとの「二重メンテ」は避けられない。ドキュメントの量に比例して、メンテナンスの工数は増え、書かれていることが「嘘」になる危険性も増大する。余計なドキュメントは書かないに越したことはない。「ドキュメントの修正工数を削る」くらいなら、「ドキュメント自体を作らない」ほうが安全である。

もちろん、ドキュメントが全く不要というわけではない。顧客との意思統一のために必要なものや、他システムとのインターフェース仕様など、削れないものはある。しかし、「誰が読むの?」というようなドキュメントを大量に書かせるプロジェクトも少なくないのには困ったものだ。

「ドキュメントはとにかく多いほうがよい」と信じている人、「いつも書いているお決まりの設計書を書いておけばいいだろう」程度に考えている人は、自分の思考停止に気づくべきである。何が必要で何が必要でないか。そして、どのように書くのが良いのか、きちんと考えることが大切だ。


このブログの順位は? ・・・


■関連記事
どこまで書くか設計書



実践!コミュニケーションドキュメント徹底活用
中村 一世 清水 秀樹
翔泳社 (2004/06/09)
売り上げランキング: 46,423
おすすめ度の平均: 5
5 よい! 顧客とのコミュニケーションを高めるドキュメントを書く力が身につく


思考停止企業
思考停止企業
posted with amazlet on 06.03.25
ジャストシステム・エンタープライズソリューション協議会/JECS
ダイヤモンド社 (2005/04/14)
売り上げランキング: 7,307
おすすめ度の平均: 4.39
5 思わず頷きながら読んでしまいます。
5 さらに一段階進んだケース・スタディとして続編を期待
4 さり気ない分かりやすさ!

いいね!した人  |  コメント(8)  |  リブログ(0)
2006年03月04日(土)

YYYY/MM/DD

テーマ:設計
「YYYYMMDD」形式で今日の日付を表せば、「20060304」である。

この「YYYYMMDD」のような表現方法は、この業界では共通の認識だと思う。

日付を8桁の固定長で表現するために、月や日が1桁の場合は前に「0」をつけて2桁をつける。1桁のままだと「1月12日」と「11月2日」が両方とも「112」になり、区別できないからだ。・・・などということは、あらためて書く必要もないことだろう。

このことから、「MM」や「DD」という表現は、日付の月や日を2桁で表記するという意味であることが分かる。

しかし、先日、ある設計書の中に、それをあえて打ち消すような表現を見つけた。

 YYYY/MM/DD形式(MM、DD は、1桁の場合には1桁で出力)

つまり、「2006/03/04」ではなく、「2006/3/4」と表すということだろう。

しかし、そのような場合、「YYYY/M/D」と書くのが普通ではないか? Excel の書式設定でもそうなっている。

おそらく、設計書を書いた人は「YYYY/MM/DD」と「YYYY/M/D」の使い分けなど知らなかったのだろう。このような「常識のズレ」とは恐ろしいもので、そのままバグに繋がることもある。

しかし、私は、彼がその代わりに「1桁の場合には云々」という但し書きを付け加えたことを評価する。これなら、誤解されることはまずない。むしろ、「YYYY/M/D形式」とだけ書くよりも意図が明確に伝わるかもしれない。そういう意味では、この1行はよく書かれているといってもいいと思う。

専門的知識が少ないとか、語彙が少ないとかいったことは、ある程度は仕方がない。技術文書を書く上でもっと重要なことは、誤解されずに意図を伝えることである。常に「この表現で誤読されないだろうか?」などと考えながら書くことが大切なのである。




← このブログを誰かに読ませたいと思った方は、クリックを


■関連記事
コンピュータに興味がないプログラマ
どこまで書くか設計書



SEを極める 仕事に役立つ文章作成術―百戦錬磨のプロマネが伝授するドキュメント作成の極意
福田 修 日本情報システムユーザー協会
日経BP社 (2005/11)

いいね!した人  |  コメント(5)  |  リブログ(0)

AD

ブログをはじめる

たくさんの芸能人・有名人が
書いているAmebaブログを
無料で簡単にはじめることができます。

公式トップブロガーへ応募

多くの方にご紹介したいブログを
執筆する方を「公式トップブロガー」
として認定しております。

芸能人・有名人ブログを開設

Amebaブログでは、芸能人・有名人ブログを
ご希望される著名人の方/事務所様を
随時募集しております。