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

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

承認ステータス: 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」にするなど、複数の修正パターンが発生するため、混乱しやすい。

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

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

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

★

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

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