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

塩谷 敦子

tag: 組み込み

技術解説 2010年8月11日

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

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

(問題点3)「電源がONのときの」は「初期化処理」の形容には不適切です

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

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

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

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

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

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

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

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

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

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

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

(問題点4)「電源ライト点灯処理」が「点灯」のみの処理を意味している場合には,表現が冗長です

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

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

組み込みキャッチアップ

お知らせ 一覧を見る

電子書籍の最新刊! FPGAマガジン No.12『ARMコアFPGA×Linux初体験』好評発売中

FPGAマガジン No.11『性能UP! アルゴリズム×手仕上げHDL』好評発売中! PDF版もあります

PICK UP用語

EV(電気自動車)

関連記事

EnOcean

関連記事

Android

関連記事

ニュース 一覧を見る
Tech Villageブログ

渡辺のぼるのロボコン・プロモータ日記

2年ぶりのブログ更新w

2016年10月 9日

Hamana Project

Hamana-8最終打ち上げ報告(その2)

2012年6月26日