最新エントリー

山本 修一郎

開発文書の複雑さを計測するにはどうしたらよいでしょうか？ 本稿では，開発文書の複雑さを，名詞句の個数に基づいて計測する方法[1]を紹介します．

■文書の複雑さの測定方法

文書を計測すると聞いてまず思いつくのは，ページ数や文字数を計測する方法です．また，文に含まれる単語を計測することもできます．単語には，接続詞や助詞などといった繰り返し出現する語も含まれます．助詞や接続詞は単独では意味を持たないので，これらを省いて名詞や名詞句，動詞だけを計測することもできます．名詞句（「寒い日」など）は，名詞（「日」）が指示する対象の属性や状態（「寒い」）を指定することができます．

基本的に，一つの文には一つの動詞が対応しているので，文の個数が動詞の個数に一致します（名詞句の中に出現する動詞は除く）．同じ個数の文を含む複数の文書を比較した場合，動詞の個数は一致しますが，名詞句（名詞を含む）の個数は異なる場合があります．したがって，動詞の個数を計測するよりも名詞句を計測するほうが，文書の複雑さを計測するのに適していると考えられています．

■名詞句の例

例として，前回も参照したNPO法人 組込みソフトウェア管理者・技術者育成研究会（SESSAME）の「話題沸騰ポット 要求仕様書」[2]第7版の要求文に含まれる名詞句を調べてみましょう．

 

[pot-320] 設定されたモードの温度にポット内の水温を保持する．

 

この例文には，「設定されたモードの温度」と「ポット内の水温」という二つの名詞句があります．

■名詞句複雑度を定義する

N個の文からなる文書に，M個の名詞句が含まれているとします．同じ名詞句が文書の中で繰り返し出てくることがあります．そこで，すべての名詞句が文書の中で1回しか出てこない場合に対して，同じ名詞句が複数回出てくる場合の方が，文書の複雑さが小さいと考えると，次のように「文の名詞句複雑度」を定義できます．

 

[定義] 文の名詞句複雑度 NPC (Noun Phrase Complexity)
j番目の文に含まれる名詞句が，文書内で出現する回数の逆数の総和を，j番目の文に対する名詞句複雑度と呼ぶ．

 

わかりやすいように，具体例を挙げてみます．なお，こちらも話題要求ポット 要求仕様書の注意書きに一部手を入れて引用しました．

 

この要求仕様書は，版数により，想定している用途が異なります．第1版～6版は，現実の開発現場でよく見受けられる曖昧さを含んだ仕様書として作成しました．曖昧部分に気づき，要求仕様書はどこまで詳細に分析し，明確に表現すべきかを考えていただける教材と考えています．第7版は，できる限 り曖昧さを無くした仕様書の例として作成しました．なお，私たちは，要求分析の最終段階ではこの記述レベルまで明確にすることを期待しています．

 

この文書は五つの文で構成されています．1番目の文には「要求仕様書」，「版数」，「想定している用途」という名詞句が含まれています．「要求仕様書」が文書内で出現する回数は2回なので，その逆数は1/2です．「版数」と「想定している用途」はそれぞれ文書内で1回ずつしか出現しないので，逆数もそれぞれ1です．つまり，1番目の文の名詞句複雑度は，2.5となります．ここでもし，2番目の文に含まれる「仕様書」を「要求仕様書」に変更すると，1番目の文の名詞句複雑度は2.3になります．

ここで，文についての複雑度の定義を基に，文書についての複雑度を示す指標として「文書の名詞句複雑度」を定義できます．

 

[定義] 文書の名詞句複雑度
文書に含まれる，文ごとの名詞句複雑度の総和を，文書の名詞句複雑度と呼ぶ．

 

例えば，N個の文からなる文書に名詞句が1個しかない場合（同じ名詞句を繰り返しており，動詞だけが異なる場合など），この文書の名詞句複雑度は1になります．一方，N個の文からなる文書にM個の名詞句があり，名詞句がそれぞれ1回ずつしか出現しない場合，この文書の名詞句複雑度はMになります．
したがって，文書の名詞句複雑度は，名詞句が文書内でどれだけ繰り返し出現するかによって減少するような尺度であるということができます．

■要求文の複雑度を計測する

それでは，話題沸騰ポット 要求仕様書 第7版に含まれる要求文を見ながら，この文書の複雑度を計測してみましょう．以下が，要求文の一覧となります．

 

[pot-210] コンセントの抜き差しで，ポットを利用できない状態／利用できる状態にする． [pot-220] アイドルの状態で，蓋を閉じたら、水位を確認し，条件に合えば沸騰行為をする． [pot-221] 蓋をあけたら（開いていたら），ロックは解除され，温度制御行為はしない． [pot-230] 保温行為中で，沸騰ボタンを押すと，沸騰行為をさせる（沸騰できる）． [pot-240] ３種類の保温の温度に設定できる． [pot-250] 給湯に対するロック／ロック解除機能を付ける． [pot-260] 給湯ボタンを押すことによって給湯口から給湯する． [pot-270] タイマボタンを押すことで，時間を分でセットし，タイマを起動できる． [pot-271] タイマボタンを長く押すことで，タイマをリセットし，タイマを停止できる． [pot-272] ユーザーが指定した時間がきたら，ブザーを鳴らして知らせる． [pot-280] ポット内の水量をインジケータで表示する． [pot-310] 水を沸騰させる． [pot-311] カルキ抜きをする． [pot-312] カルキ抜きが終わったら，保温行為をする． [pot-320] 設定されたモードの温度にポット内の水温を保持する． [pot-330] 沸騰行為も保温行為もできないときは温度制御はしない． [pot-400] ヒータをon/offすることにより水温を制御する．その制御方式は制御周期と操作量(％)により行う． [pot-500] 想定外の高温状態になった場合はエラーを検知し，ヒータ機能を停止する．

 

話題沸騰ポットの要求文の個数は18個です．この要求文には41個の名詞句があります．この中に，1回しか出現しない名詞句が35個，2回出現する名詞句が4個，3回出現する名詞句が2個ありました（図1の青い実線を参照）．したがって名詞句の出現回数は49です．

ちなみに，2回出現する名詞句は，「蓋」「タイマボタン」「カルキ抜き」「保温行為」．3回出現する名詞句は「沸騰行為」と「タイマ」です．なお，名詞も修飾語のない名詞句として数えています．

 

図1　話題沸騰ポットの名詞句数と出現回数

 

上述した方法で，話題沸騰ポットの要求文18個に対する文書の名詞句複雑度を計算すると約41となり，名詞句の個数である41に近い結果になりました．したがって，名詞句複雑度から見ると，かなり複雑だということになります．

話題沸騰ポットの要求文に含まれる名詞句には類似するものもあるので，表現を見直すことにより，名詞句ごとの出現頻度を向上できる可能性があります．たとえば，繰り返し出現する名詞句を増やすことができれば（図1の赤い点線を参照），この要求文書に対する文書の名詞句複雑度を減らすことができます．

 

参考文献
[1] Chao Y. Din, Requirements Content Goodness and Complexity Measurement Based On NP Chunks, VDM Verlag Dr.Muller, 2008
[2] 組込みシステム教育教材 話題沸騰ポット GOMA-1015型 要求仕様書，http://www.sessame.jp/workinggroup/Wo ... up2/POT_Specification.htm
 

 

山本 修一郎

開発文書では，「分からないものを書く方が悪い」という姿勢が大切です [1]．後続工程の開発者が先行工程の開発文書を読んでも分からなかったら，自分の想像によって補うことになります．これでは，後続工程で先行工程の活動をやり直すことになってしまいます．

■短文を書く

分かりやすい文章の第1条件は，文が短いことです．文が長くなればなるほど，分かりにくくなります．
日本語の短文に含まれる平均文字数の目標は約50字だそうです [1]．試しに，NPO法人 組込みソフトウェア管理者・技術者育成研究会（SESSAME）がサンプルとして提供している要求仕様書「話題沸騰ポット」の要求文に含まれる平均文字数を数えてみると，約26字でした．この要求仕様書は，短文性が高いと言えます．

■表現を統一する

文が短くても，開発文書に含まれる表現が多様だと分かりにくくなることがあります．
  「表現」と「意味」という関係から構文をとらえると，「異なる表現が同じ意味を持つ場合（表現の揺れ）」と，「同じ表現が異なる意味を持つ場合（意味の揺れ）」があります．どちらも，文書を理解する上で，問題があると思います．分かりやすい文章を作成するためには，表現の揺れと意味の揺れを減らす必要があります．

表現の揺れと意味の揺れは，「用語」と「構文を構成する要素」の両方に対して発生します．用語に対する揺れは，用語集を作成することにより解消できます．以下では，構文を構成する要素 に対する揺れについて説明します．

■複数の意味をもつ助詞はできるだけ使わない

「で」と「は」という助詞には，複数の意味があります．「で」には，「手段」と「状態」，「場所」を示す場合があります．「は」には，「主語」と「対象範囲」を示す場合があります．複数の意味を持つ助詞は，書く方からすれば使い勝手が良いものです．しかし，どの意味なのかを読み手が判読する必要があるため，理解しにくい面があります．このため，「で」と「は」をできるだけ使わないようにすることにより，分かりやすい文になります．

■「ことで」or「ことにより」

手段や目的，関係を表現するためには，「ことで」，「ことにより」，「によって」，「して」，「たら」，「と」などが用いられます．開発文書では，あえて異なる助詞を使い分ける必要があるとは思えないので，統一することが望ましいでしょう．

例えば，先ほど例に挙げた話題沸騰ポットの要求仕様書の記述[2]では，18個の要求文の中に8個の手段記述があるのですが，この8文の中で6種類の手段表現が使われています．もし手段表現を「により」に統一すれば，使用単語数を削減できます．

■「ときは」or「場合は」

システムや対象物の状態を表現するためには，「に」，「で」，「たら」，「ときは」，「場合は」，「ならば」などが用いられます．状態表現を統一することにより，使用単語数を削減できます．

■「する」or「させる」or「を行う」

機能表現にも揺れが発生します．話題沸騰ポットの記述[2]では，次の8種類の表現が出現します．①「～を～する」，②「～できる」，③「～させる」，④「～をする」，⑤「～をさせる」，⑥「～を行う」，⑦「～機能を付ける」，⑧「～しない」．

さらに，それぞれの機能表現が2～3回ずつしか使われていません．これらを1つの機能表現に統一することにより，文書作成だけでなく文書理解も容易にできます．

■改善のためには測定が有効

分かりやすい文章を書くためには，文を短くすることと，表現の揺れや意味の揺れを減らすことが重要であると述べました．試しに，開発文書に含まれる単文の文字数を測定してみてください． また，単語の出現頻度と意味種別を測定してみてください．実際に，自分たちが作成している開発文書を測定し，見直してみることにより，短文性が向上し，表記揺れを減らすことができます．

なお今回は，構文を構成する要素についても，単語間の関係やパラグラフ内の論理構造，パラグラフ間の関係などについては触れませんでした．これらについては，次回以降，考察していく予定です．

 

参考文献

[1] 下村耕平，これからの技術文書，国際化時代の技術者・翻訳者必携，競争に勝つドキュメンテーションの論理と方法論，アルカ，1987
[2] 組込みシステム教育教材 話題沸騰ポット GOMA-1015型 要求仕様書，http://www.sessame.jp/workinggroup/Wo ... up2/POT_Specification.htm