商品単価取得メソッドの例
もうひとつ例を挙げましょう。プログラムのとあるメソッドの仕様解説です。
商品単価を取得するメソッドの仕様
（知らない人への解説としては不適切な書き方）
- メソッド名：ShouhinTanka
-
引数：
int ShouhinCode（商品コード）
DateTimeOffset TorihikiBi（取引日） - 返値：decimal（商品単価）
-
解説：
引数で与えられた商品コードと取引日を使って、テーブルXXXから1レコードを取得する。データベースアクセス時の例外はロギングしてからリスローする。取得できたレコード数が1以外なら、ロギングしてからDataExceptionをスローする。
取得したレコードから単価を取り出す。単価が負の値のときは、ロギングしてからDataExceptionをスローする。取得したレコードから消費税率を取り出す。消費税率が負の値のときは、ロギングしてからDataExceptionをスローする。
取り出した単価と消費税率を用いて、税込単価を計算する。計算式は次の通りで、小数点以下は銀行丸めの四捨五入とする。
［税込単価］＝［単価］×（100＋［消費税率］）÷100
計算時の例外はロギングしてからリスローする。計算した税込単価を返す。
慣れた開発者にとっては、どうということもない説明に見えるかもしれません。でもこれにも、ハイブリッドカーの最初の解説と同様の問題があります。「これは何をするメソッドなのか？」ということが、熟読してみないと分からないのです。
上の解説を理解するには、何回も読み直すことになるでしょう。繰り返し読む中で、「ああ、そうか、税込単価を計算して返せばいいのか」、「なるほど、例外をキャッチするのはそういうときか」、「あ、こういうときには例外を出さなきゃいけないのか」……と、ちょっとずつ頭の中に入ってきます。ならば、解説が初めからそのように書かれていた方が楽に理解できるでしょう。読み手の理解がどのように進んでいくかを想像して、それに沿って書いていくのがステップアップ型です。
では、この仕様にも不正確ではあっても簡単な説明を先頭に追加しましょう。そのために「概要」という項目を追加します。解説の本文もステップアップ型に書き直しましょう。また、さらに理解しやすくなるように、メソッド名なども変えてみます。そのように書き直してみた仕様を次に示します。
商品単価を取得するメソッドの仕様
（知らない人への解説として適切な「ステップアップ型」の書き方）
- メソッド名：GetShouhinTankaWithTax
-
引数：
int ShouhinCode（商品コード）
DateTimeOffset TorihikiBi（取引日） - 返値：decimal（消費税込み商品単価）
- 概要：商品コードから単価（消費税込み）を取得する
-
解説：
引数で指定された商品の単価と消費税率をデータベースから取得し、消費税込み商品単価を計算して返す。
引数で与えられた商品コードと取引日を使って、テーブルXXXから1レコードを取得する。取得したレコードから単価と消費税率を取り出し、税込単価を計算して返す。
税込単価の計算式は次の通りで、小数点以下は銀行丸めの四捨五入とする。
［税込単価］＝［単価］×（100＋［消費税率］）÷100なお、以下の例外はキャッチし、ロギングしてからリスローする。
- データベースアクセス時に発生した例外
- 税込単価の計算時に発生した例外
以下の場合はエラーとし、ロギングしてからDataExceptionをスローする。
- テーブルXXXから取得できたレコード数が1以外のとき
- 取得したレコードから取り出した単価が負の値のとき
- 取得したレコードから取り出した消費税率が負の値のとき
概要を追加しただけでなく、解説本文でも第1段落で簡単に説明してから、第2段落以降で詳しく説明しています。また、例外処理は後ろにまとめました。変更前と比べて、ずいぶん読みやすくなったと思います。
まとめ
リファレンスでは正確性と網羅性が重視されます。それに対して技術解説では、理解のしやすさが最優先です。分かりやすく伝えるための工夫として、最初に不正確ではあっても簡単な説明をしてからちょっとづつ詳しく説明を加えていくという「ステップアップ型」の書き方を紹介しました。
