ソフトウェア技術者のためのバグ百科事典(6)不信感を生む“文書作成のバグ”山浦恒央の“くみこみ”な話(127)(3/3 ページ)

» 2020年03月16日 11時00分 公開
前のページへ 1|2|3       
※本記事はアフィリエイトプログラムによる収益を得ています

5.文書作成バグの兆候と対策

5.1 兆候

 文書作成のバグには、発生する兆候はなく、作成者の力量が試されます。

5.2 対策

 文書作成バグの対策法を以下に示します。

5.2.1 文書校正ツールを使用する

 皆さんが普段使用するマイクロソフトの「Word」には、文書校正機能が付いています。機能を有効にしておくと、完全ではありませんが、明らかな間違いを指摘してくれます。例えば、過去に筆者が間違えた「Deadrock」もエラーであると指摘します。

5.2.2 間違えやすい文字を一括検索する

 間違えやすい文字は、文面を追っているだけでは分かりません。そこで、「メモリの解放とメモリの開放」「シミュレーションとシュミレーション」のような間違えやすい単語をまとめておき、文書を見直す際に検索をかけましょう。

5.2.3 紙に印刷する

 不思議なことに、PCの画面で見るより、紙に印刷したほうが間違いを見つけやすくなります。若者は目がよいので必要性を感じないでしょうが、間違いの多いエンジニアは印刷して、図番号などを再チェックすることが望ましいでしょう。

5.2.4 数日寝かせる

 作成したプログラムを3日後にもう一度確認してみると、「何でこんな書き方をしたのだろう」と思うことがありますね。文書作成でも同じで、文書の間違いが多く見つかります。時間に余裕がある場合は、数日後に再確認することをお勧めします。

5.2.5 レビューを依頼する

 周りの人にレビューを依頼するといいでしょう。いくら自分で自信を持った文書を記述しても、他の人から見るとおかしい箇所が多く見つかります。ただし、付箋紙や口頭での修正指示などをすると意思疎通の関係上、終わらなくなることがありますので、指摘者自らが修正することを強くお勧めします。

5.2.6 実行可能な仕様書を作成する

 図の記述方法によっては、ツールで実行結果を確認できるものがあります。状態遷移図ならば、Simulink/Stateflowなどのツールを使うと、シミュレーションで確認できます。ツールがない場合は、状態遷移表を参考に机上デバッグしてみてください。ペンで追っていくうちに間違いが見つかります。

6.まとめ

 下記に文書作成のバグをまとめます。

  • 文書作成のバグは、文書の形式上のエラーのことであり、このバグが開発対象に大きな影響を与えることはほとんどないが、顧客に不信感を与える可能性がある
  • 文書作成のバグは、主に、誤字脱字、図や表番号を付け忘れる、図・表の作成ミスがある
  • 文書作成のバグの兆候はなく、作成者の力量による
  • 文書作成のバグを防ぐためには、「文書校正ツールを使用する」「間違えやすい文字を一括検索する」「紙に印刷する」「数日置いた状態で再確認する」「レビューを依頼する」「実行可能な仕様書を作成する」などの対策をするとよい

7.終わりに

 ソフトウェア開発業務の中で大きな比率を占める作業の一つが、文書作成でしょう。今回は、筆者の経験を踏まえた文書作成のバグを取り上げました。このバグは、プログラムの動作に大きな影響を与えることはありませんが、顧客の信頼を確保するために、キチンとした文書を提出できるようにしましょう(誤字脱字衍字などのエラーが多いと、仕様や設計のバグも多いと考えます)。ただし、形式的なバグばかりを気にしすぎて、本質のバグを見落とすことがないように気を付けてください。

 本シリーズのバグ百科事典は、バグに関する基礎知識を増やすためのものですが、実践力を磨きたいという方は、過去シリーズか書籍の「バグ検出ドリル」に挑戦していただければと思います。

山浦先生執筆の書籍「ソフトウェア技術者のためのバグ検出ドリル」が発売!

 2019年11月27日に、山浦恒央先生が執筆した書籍「ソフトウェア技術者のためのバグ検出ドリル」が日科技連出版から発売されました。本連載「山浦恒央の“くみこみ”な話」とTechFactoryの連載「組み込みエンジニアの現場力養成演習ドリル」をベースに、大幅加筆、改訂した内容になっています。

 内容は、「デバッグの詰将棋」で、要求仕様定義、設計、コーディング、テスト、保守の5フェーズでの「バグを埋め込んだ仕様記述やソースコード」を読んで、バグをピンポイントで見つける問題集になっています。全部で31問あり、難易度は初級から上級まで、いろいろです。興味のある方は、Amazon.comや書店でチェックしてください!

【 筆者紹介 】
山浦 恒央(やまうら つねお)

東海大学 大学院 組込み技術研究科 非常勤講師(工学博士)


1977年、日立ソフトウェアエンジニアリングに入社、2006年より、東海大学情報理工学部ソフトウェア開発工学科助教授、2007年より、同大学大学院組込み技術研究科准教授、2016年より非常勤講師。

主な著書・訳書は、「Advances in Computers」 (Academic Press社、共著)、「ピープルウエア 第2版」「ソフトウェアテスト技法」「実践的プログラムテスト入門」「デスマーチ 第2版」「ソフトウエア開発プロフェッショナル」(以上、日経BP社、共訳)、「ソフトウエア開発 55の真実と10のウソ」「初めて学ぶソフトウエアメトリクス」(以上、日経BP社、翻訳)。


前のページへ 1|2|3       

Copyright © ITmedia, Inc. All Rights Reserved.