理系のための文書作成術(1) ―― 開発文書を分かりやすく記述する

●ソフトウェア開発文書を意識した改善点も見つけてみましょう

　上記の2点を改善できたとしても，例文の「電源がONのときの初期化処理（あるいは電源ライト点灯処理）」という記述では，意味を適正に解釈できるでしょうか？（以降，説明を分かりやすくするために，「電源ライト点灯処理」に関する個所は省略する）

　「電源がONのときの」を素直に読み換えると，「電源がONであるときの」となります．つまり，「電源がONの状態のときの」と解釈できます．ここで，「電源がONである状態のときの初期化処理」という記述に，ソフトウェア開発文書内の表現として少し奇妙な印象を受けませんか．
「初期化処理」は，通常何らかの事象（イベント）に同期して行う処理を表す言葉として用います．「電源がONの状態のときの」は状態を示しており，その状態中のいつどんなときの「初期化処理」かを，明示していません（図1）^注2．

図1　「電源がONの状態のときの初期化処理」を図示したもの

注2：本稿内の図は，UMLシーケンス図の表記方法を参考にして，特に「状態」と「事象（イベント）」の違いを表すために，独自の記述方法にて表現したものである．図1と図2では，「初期化処理」を行うものを，仮に「システム」と想定して表現した．

　それでは，「電源がONの状態のときの」という形容句を，状態ではなく，「電源がONになったときの」という事象を表す形容句に変えてみます．これなら，「初期化処理」を「いつ実施するか」を特定でき，明確な表現になります（図2）．

図2　状態ではなく事象を表す表現に変えたもの

　実は，このような表現は，ソフトウェア開発文書に限らず，一般の文書内にも見かけることがあります．例えば「日本シリーズ開幕中の始球式」，「マンションを借りているときの敷金支払い」などは，同じように，「始球式」や「敷金支払い」に対して状態の表現による形容句がかかっています（図3）．

図3　「日本シリーズ開幕中の始球式」を図示したもの

　この形容句を，例えば，「日本シリーズ開幕時の」と「マンションを借りたときの」といった事象の表現に変えることで，「始球式」や「敷金支払」が「いつのことか」を特定した記述になります（図4）．

図4　状態ではなく事象を表す表現に変えたもの

　「初期化処理」，「始球式」，「敷金支払い」は，特定の動作に関連する言葉です．このような，名詞や名詞句，また，動作を示す動詞や動詞句（「初期化処理を実施する」，「始球式を行う」，「敷金を支払う」）に対して，「事象」の表現を意識することは，より正確な動作の表現につながります．一般文書では，なんとなく通じるために許容される表現でも，特に，開発文書では厳密に正確に表現したいものです．

　さらに，ソフトウェア開発文書としては，次の点も気になる記述と言えます．

　単に「点灯」のみの処理である場合は，「電源ライトを点灯する」と書く方が，より直接的に意味を伝えることができます．「点灯」するだけであるなら，わざわざ「点灯処理」と書く必要はありません．「～処理」と書いたことで，読み手は，何か特別な処理やいくつかの処理をまとめた表現であることを想像する可能性があるからです．処理が単独の場合には，処理名をつけて抽象化するより，単独で実施する事柄のみをシンプルに表現する方が明確になります．

　ただし，別の個所で「電源ライト点灯処理」という見出しの処理が定義されているか，後で定義するつもりの場合には，「電源ライト点灯処理」という処理名であることを明示するように書きましょう．なお，その場合には，「X.Y節に定める電源ライト点灯処理」と，参照元や引用元などの関連する個所を明記するとよいでしょう．