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

塩谷 敦子

tag: 組み込み

技術解説 2010年8月11日

●改善点を見つけてみましょう

 次の例文は,筆者がある組み込みソフトウェア開発の仕様書内で見つけた記述です.分かりにくい個所を指摘してみてください.

[例文]
本モジュールでは,電源がONのときの初期化処理,電源ライト点灯処理を実施する.

 短い1文の中で,いくつの分かりにくい点が見つかりましたか.実際の仕様書では,この文の前後にも記述が存在します.1文だけでは分かりにくい(一意に解釈できない)点であっても,文脈から判断できる場合もあります.ここでは,他の個所の記述によって想定できる点は除き,1文のみから読み取れる改善点を指摘してみましょう.例えば,例文中の「初期化処理」という表現において,「何を」初期化するかは他の個所に記載されているものとします.

 筆者は,この1文から,改善できそうな点を4点見つけました.

(問題点1)読点でつないだ文節「電源が......初期化処理,」と「電源ライト....実施する」の関係があいまいです

 例文では,次の3通りの解釈ができてしまいます.

  • 言い換え:「初期化処理として電源ライト点灯処理を実施する」
  • 並列:「初期化処理と電源ライト点灯処理を実施する」
  • 順接:「最初に初期化処理を実施し,続いて電源ライト点灯処理を実施する」

 複数の事柄を並べて記述するときには,それらの事柄同士が意図と異なる関係に解釈されないかに注意して,あいまいさを避ける記述を心がけましょう.

(問題点2)「電源がONのときの」がどこにかかるかが不明です

 「初期化処理」だけにかかるように読みとれます.しかし,「初期化処理」に加えて「電源ライト点灯処理」にもかかるととらえることもできてしまいます.

 このように,複数の解釈を誘う記述は,開発対象であるソフトウェアを意図しない仕様のものに導いてしまいます.そして,分かりにくい記述を含む仕様書は,開発のための重要な情報を明確に示せずに,かえって開発の妨げになる危険性を持っています.

 このような改善するべき記述の検出には,特別なソフトウェアの知識は必要ありません.日本語表現として分かりにくい点を指摘することが,ソフトウェア開発上のあいまいさを発見することにつながります.

組み込みキャッチアップ

お知らせ 一覧を見る

電子書籍の最新刊! 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日