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)

argvさんの読者になろう

ブログの更新情報が受け取れて、アクセスが簡単になります

コメント

[コメントをする]

3 ■仰るとおり

ソースにリテラル直で書いて、品質が云々と言い設計書のレビューに1、2時間。コードの品質が上がらないとアプリの品質上がらないですよね。

2 ■RE: 無題

サトシさん、応援ありがとうございます。

1 ■無題

ちょくちょく拝見しています。
応援ポチッ!

コメント投稿

AD

ブログをはじめる

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

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

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

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

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