移動: トップ > ラボ > 文章の書き方 > レポート文章の作り方
アイディアを説明する文章の書き方 | メトリクスを測って文章の質を上げる
履歴:
統計:
目次:
このページの最終更新日: 2012/05/29
提案日: 2010/07/25

レポート文章の作り方

概要

概要文章
○ 短い背景+をするかの短い説明(どちらにも一番分かりやすく短い具体例を使う、まとめではない)
○ 「~するといったアイディアです。」の形で終わる
○ これによって現在よりもよくなること

レポート課題が出されたときに、まっさらな状態からいきなり書き始めようとしても、なかなか筆が進まず、何を書いたらよいのかと書き始めの時点で止まってしまいます。

そこで、レポートなどのように、何らかのテーマについて構成立てて書く必要のある文章を、どのようにして書けば、分かりやすい文章素早く書けるか、その方法についてここにまとめます。

背景

サクサクっと書いて完成させたいレポート

背景文章
○ これが出てきた過程、これを思いつくまでの経緯、世の中の必要性などを書く。
○ 「そこで、~する、といったアイディアに至りました。」の形で終わる。
○簡単な言葉で書ける必要なことだけを短く書く。詳細な背景は後で書く。

ある研修に参加した際に、1つのレポートを提出する必要がありました。Wordで2~3ページ程度あるレポートでしたが、まっさらな状態からいきなり書き始めようとしても、なかなか筆が進まず、何を書いたらよいのかと書き始めの時点で止まってしまいました。

それほど力を要れずにサクサクっと書いて完成させたいところでしたが、ただ何か書こうというだけでは一向にレポートが書けません。これでは時間が過ぎていくだけで、このままではだめだと分かりました。何か戦略的なやり方で、スマートにレポートを書いていく方法があればと感じました。

そこで、このレポートでいろいろと方法を試してみました。以前から文章にまとめる作業は何かと必ずあったので、それらの経験も含めながら、思い付く方法をいろいろ試しました。すると、うまく書ける場合があることが分かってきました。そのため、レポートをまっさらな状態から書き始めるときに、スマートにレポートを書いていく方法をここにまとめます。

どんなもの?

箇条書きから始める

方法文章
○「背景」からの流れを使わず、ここから読んでも分かるように新しく文章を書き始める。
○はじめに筆者が想像するその具体的な場面状況をまず読者に伝える。「~ときに/~の場合を考えます」のようなフレーズを使う。
○状況設定の後、そのアイディアがどんなものなのかを一言(最も短い例)で書く。 「~といったアイディアです。」のようなフレーズを使う。限定しすぎたり不足があっても後の文章で修正できる。
○一言説明の後、アイディアの説明を1つの例に限定してそのシナリオ全部を書く。
取り残した部分、利点性質後で書く。

レポートなどのように、何らかのテーマについて構成立てて書く必要のある文章を、どのようにして書けば、分かりやすい文章素早く書けるか、その方法についてここにまとめます。

ここでまとめるレポートを書く方法は、端的に言えば、次のような手順で書くものになります。

  1. 書きたい内容を思いつくまま箇条書きする
  2. 箇条書きした項目を階層化したり、順序を入れ替え整理する
  3. それを基に、足りない説明を肉付けすることで文章を作る
  4. 数日寝かせた後にもう一度読み返して清書する

書き始めは、いきなり清書版レベルの文章を書くのではなく、思いつくままに箇条書きすることから始めます。これで、スタートのハードルがぐっと下がります

箇条書きで項目を挙げたら、次にこれらを整理します。思い付いた順に並んでいるので順番を入れ替えたり、まとめられるかたまりがあればグループにしてツリー状に階層化したりします。この整理の中で、抜けていた項目が見つかったり、新しく項目を思い付くことがあります。これらもすぐに箇条書きに含めて、内容を拡充します。

整理した箇条書きを基にして、文章を書きます。箇条書きだけでは足りない説明を肉付けする感覚で文章を作ります。想定している場面を説明する文章を前に加えたり、箇条書きの中のキーワードを具体的に説明する文章を後に加えたりします。

すべての箇条書きを文章にしたら、それを数日放置した後に、もう一度読み返して清書します。これによって、読みにくい日本語になっている部分や、説明の足りない部分などに気付きます。このような細かな部分を修正して、文章を完成させます。

端的には : 箇条書きにして→階層化/整理して→足りない説明を文章で肉付けすることで文章を作って→数日寝かせた後に読み返して清書する

具体的にレポートを作るには?

実際にレポートをどのような感じで作っていくのかを見るために、具体的にレポートを作っていく例を紹介します。ここで紹介するレポートは、ある研修に参加した際に出題された1つのレポート課題に対して、前述のレポートを書く方法を適用して、実際にレポートを作って提出したものです。

Wordで2~3ページ程度のレポートで、課題は次のような組込みソフトウェアの開発方法に関するものです。

  • [課題] 組込み機器の開発において、ターゲットマシンが直ぐに入手できず、且つ、非常に短期間しか利用できない状況下で、どのようにデバッグ/テストを行えばよいかについて記述しなさい。

組込み機器やターゲットマシンなど、かなり限られた分野の話ですが、内容は無視して、レポートがどのように作られていくかに注目して見てください。

ここで紹介するレポートは、次の5つです。前述のレポート課題に対して、書き始めから完成までの過程を追った5つのバージョンです。これらを順に見ていくことで、次第にレポートが作られていく様子が分かります。

  レポートVer.1   1. 箇条書きから書き始め
  レポートVer.2   2. 箇条書きに項目を足して整理
  レポートVer.3   3. 文章を書き始め
  レポートVer.4   4. すべての文章を書く
  レポートVer.5   5. 読み返して修正/完成させる

1. 箇条書きから書き始め

書き始めたばかりのレポートVer.1を次に示します。まっさらな状態から、思いつくままに箇条書きし始めたところのレポートです。

  • 組込み移行起因のバグ以外のバグを全て洗い出して修正を完了しておく戦略
    • バグの発生起因が異なる、それぞれの段階で確実に対処すること
    • アルゴリズムの単体テスト
    • メモリ破壊チェックなどのシミュレーション/負荷テスト
    • タスクスケジュリングに伴う誤動作チェックなどのシミュレーション/負荷テスト
    • CPUエミュレータで動作検証
  • 最後に組込み機器へ実装、というよりは移植に近い… 理想的にはコンパイルし直し→転送→テスト→終了の感じ
作成中のレポートVer.1 : 箇条書きから書き始め

上記のレポートは、Word形式でダウンロードできます
(ファイル名 : report_v1.doc)

書き始めは、このようなツリー状の箇条書きを作ります。思い付くアイディアの中から、何を書くかを箇条書きにして、おおまかなスケッチアップを作ります。

箇条書きの項目は、文章の形でなくても構いません。使う日本語は、分かりにくい表現になっていても構いません。短期間、自分だけが分かればよいメモなので、不完全でも大丈夫です。それよりも、ここでは早く書き残すことを優先します。必要であれば、次のように記号などを使って、素早く表現します。

  • 「ABC」のように、順序のある項目を矢印でつなげて書く
  • 「~する (~のこと)」のように、メモ書きを括弧で書く
  • 「ABC」のように、並列の項目を「/」で区切って書く
  • 「~する (ex: ~のこと)」のように、「ex」と書いて具体例の部分を明示する
  • 「AB」のように、左矢印でAに対する理由注釈を書く
  • 「~する [名前A]」のように、大括弧で項目に名前を付けて、他の部分で参照する

書き始め、メインアイディアを基に何を書くかラフなスケッチアップ、日本語は変な言い回しでもOK←短期間の間自分だけが分かればよいので、それより早く書き残すことを優先する

2. 箇条書きに項目を足して整理

レポートVer.2を次に示します。レポートVer.1の箇条書きからさらに項目を加えて、全体の階層をより整理したレポートです。レポートVer.1から項目を足した部分は青色の下線項目を整理/変更した部分は黄色の下線で示してあります。

  • 組込み移行起因のバグとそれ以外の分離
    • 組込み移行起因のバグ以外のバグを全て洗い出して修正を完了しておく戦略
    • バグの発生領域の明確化
      1. 計算アルゴリズムに起因する領域
        (処理方法、計算数式、コード化以前の問題領域)
      2. メモリ操作コードに起因する領域
        (オーバーラン、オーバーフロー、メモリ破壊、解放忘れ)
      3. 並列タスク処理に起因する領域
        (スケジュリングミス、排他制御ミス、共有データ破壊)
      4. 組込み移行に起因する領域
    • バグの発生領域に対する事前テスト/シミュレーションの徹底
      1. アルゴリズムの単体テスト
      2. メモリ破壊チェックなどのシミュレーション/負荷テスト
      3. タスクスケジュリングに伴う誤動作チェックなどのシミュレーション/負荷テスト
      4. CPUエミュレータで動作検証
  • 最後に組込み機器へ実装、というよりは移植に近い
    想的にはコンパイルし直し→転送→テスト→終了の形態
  • それでも発生するバグのために…
    • 関数呼び出しログ記録機構
    • 関数呼び出しパラメータチェック機構
    • システムコール/上位関数
    • ログテキストは構造化して読みやすくする
    • メモリ状態を容易に取得、簡単に理解しやすくする

これらは、ターゲットが利用できない場合に限らず、転送速度が遅い、ターゲットが発展途上でバグが多く混入/不安定、ターゲットに物理的な要因でエラーが発生する(電源不安定、熱影響、内部故障、外乱ノイズ、放射線etc)、の場合にも同様に有用な手法で、応用が可能。

作成中のレポートVer.2 : 箇条書きに項目を足して整理

上記のレポートは、Word形式でダウンロードできます
(ファイル名 : report_v2.doc)

このように箇条書きの項目を追加/組み換えして、構成を整理していきます。各項目の違いが明確になるように、項目の内容を推敲します。項目を意味のある単位ごとにツリー状に階層化したり、流れのある場合は番号を振って整理します。

時間が経つうちに、他に思い付いた別トピックを追加して、箇条書きのスケッチアップを拡充していきます。内容が足りない場合は、項目をよく整頓して、順番に並べたときに抜けているものや、反対になるものを考えて、新しい項目を発掘します。

箇条書き項目の構成変更、各項目の違いを明確化、項目の整頓から新しい項目の発見、項目を階層化/順序付けして整理、時間が経つうちに他に思い付いた別トピックを追加してラフにスケッチアップ

3. 文章を書き始め

レポートVer.3を次に示します。 レポートVer.2の箇条書きしたスケッチアップを基に、説明を肉付けする感覚で文章を書き始めたレポートです。レポートVer.2から書き足した部分は青色の下線整理/変更した部分は黄色の下線で示してあります。

ターゲットマシン上で短期間しかデバッグ/テストできないので、それまでに出来ることをやっておく対策を講じる。対策は、開発対象に含まれるバグ全体のうち、ターゲットマシンへの移行によって生じるバグとそれ以外の全てのバグに分離して考え、ターゲットマシン上へ移行する前に、移行起因以外の全てのバグを洗い出し、修正を完了させるようにする。

ここでは、開発対象に含まれるバグ原因の領域全体を、次の4項目に分離して考える。

  1. 計算アルゴリズムに起因する領域
    (処理方法の間違い、計算数式の間違い、コード化以前の理論的な問題など)
  2. メモリ操作処理に起因する領域
    (オーバーラン、オーバーフロー、メモリ破壊、解放忘れなど)
  3. 並列タスク処理に起因する領域
    (スケジュリングの間違い、排他制御の間違い、共有データ破壊など)
  4. ターゲット移行に起因する領域
    (上記以外のターゲット特有のバグ)

このうち、ターゲットマシン上へ移行する前に、バグ原因領域の「1.」から「3.」の全てのバグを洗い出し、修正を完了させる。そのために、バグ原因領域、事前テスト/シミュレーションの徹底■

  1. アルゴリズムの単体テスト
    (アルゴリズム自体の正常動作を個別に確認する)
  2. メモリ操作部分の単体テスト/負荷テスト
    (メモリ操作に関わる隠れたバグを洗い出す)
  3. タスクスケジュリングの動作シミュレーション/負荷テスト
    (スケジュリングに伴う予期せぬ誤動作を洗い出し)
  4. CPUエミュレータで動作検証
    (仮想環境で摘出可能なターゲット移行起因のバグを早期解決)

------------------------------↓スケッチアップ------------------------------

  • 組込み移行起因のバグとそれ以外の分離 [A]
    • 組込み移行起因のバグ以外のバグを全て洗い出して修正を完了しておく戦略 [B]
    • バグの発生領域の明確化
      1. 計算アルゴリズムに起因する領域
        (処理方法、計算数式、コード化以前の問題領域)
      2. メモリ操作コードに起因する領域
        (オーバーラン、オーバーフロー、メモリ破壊、解放忘れ)
      3. 並列タスク処理に起因する領域
        (スケジュリングミス、排他制御ミス、共有データ破壊)
      4. 組込み移行に起因する領域
    • バグの発生領域に対する事前テスト/シミュレーションの徹底(下記順) [C]
      1. アルゴリズムの単体テスト
        (アルゴリズム自体の正常動作を個別に確認する)
      2. メモリ操作部分の単体テスト/負荷テスト
        (メモリ操作に関わる隠れたバグを洗い出す)
      3. タスクスケジュリングの動作シミュレーション/負荷テスト
        (スケジュリングに伴う予期せぬ誤動作を洗い出し)
      4. CPUエミュレータで動作検証
        (仮想環境で摘出可能なターゲット移行起因のバグを早期解決)
  • 最後に組込み機器へ実装、というよりは移植に近い
    理想的にはコンパイルし直し→転送→テスト→終了の形態
  • それでも発生するバグのために…
    • 関数呼び出しログ記録機構
    • 関数呼び出しパラメータチェック機構
    • システムコール/上位関数
    • ログテキストは構造化して読みやすくする
    • メモリ状態を容易に取得、簡単に理解しやすくする

これらは、ターゲットが利用できない場合に限らず、転送速度が遅い、ターゲットが発展途上でバグが多く混入/不安定、ターゲットに物理的な要因でエラーが発生する(電源不安定、熱影響、内部故障、外乱ノイズ、放射線etc)、の場合にも同様に有用な手法で、応用が可能。

作成中のレポートVer.3 : 文章を書き始め

上記のレポートは、Word形式でダウンロードできます
(ファイル名 : report_v3.doc)

このように、箇条書きしたスケッチアップを基に文章を書き始めます。上の例では、箇条書きの項目[A][B]の内容をはじめに文章で説明して、その下に箇条書きの内容をそのまま移しています。このように、箇条書きの内容に入るまでの書かれていない想定状況や、箇条書きの内容では足りない言葉を文章で肉付けするように説明します。可能であれば箇条書きの項目をそのまま移して活かします。

ここで書き出す文章は、まだ綺麗な表現でなくて構いません。文章の流れが少し変であっても、とりあえず文章にしてみることが大切です。ここで適切な文章に悩んでしまうと、時間があっという間に経ってしまい、レポートを書くのに多くの時間が掛かってしまいます。素早くレポートを作るためには、完成度が低くてもここで文章を書いておき、後で読み返すときに直すようにします。このように、徐々に完成のレベルを上げていく感じで、段階的にレポートを作ります。

イメージがはっきりしていて書きやすい箇条書きから文章にしていきます。ぼんやりした部分は後に回して、先に何らかの文章が出来上がることを目指します。文章を書いていると、先ほどまでぼんやりしていた部分が次第に分かってくる場合があります。出来るところから順にレポートを作ります。

文章を書いた箇条書きの項目は取り消し線でチェックして、書き終わりをはっきり示します。文章で途中書きの部分には「」でマーキングして、追加/修正が必要なことを示します。上の例では、箇条書きの項目[C]の内容がまだ途中書きなので、文章の中に「■」のマークを付けています。

スケッチアップを基に本文章を書き始め、足りない想定状況や省略表現した内容を肉付けして説明、箇条書き項目はそのまま本文章へ活かす本文章を書いた項目は取り消し線でチェック、本文章の書き途中の部分には「■」でマーキング。
イメージがはっきりしていて書きやすい箇条書きから書いていきます。ぼんやりした部分は後に回して、先に何らかの文章が出来上がることを目指します。

4. すべての文章を書く

レポートVer.4を次に示します。レポートVer.3で書き始めた文章を最後まで書いて、箇条書きから文章作成を完了させたレポートです。レポートVer.3から書き足した部分は青色の下線整理/変更した部分は黄色の下線で示してあります。

ターゲットマシン上で短期間しかデバッグ/テストできないので、それまでに出来ることをやっておく対策を講じる。対策は、開発対象に含まれるバグ全体のうち、ターゲットマシンへの移行によって生じるバグとそれ以外の全てのバグに分離して考え、ターゲットマシン上へ移行する前に、移行起因以外の全てのバグを洗い出し、修正を完了させるようにする。

ここでは、開発対象に含まれるバグ原因の領域全体を、次の4項目に分離して考える。

  1. 計算アルゴリズムに起因する領域
    (処理方法の間違い、計算数式の間違い、コード化以前の理論的な問題など)
  2. メモリ操作処理に起因する領域
    (オーバーラン、オーバーフロー、メモリ破壊、解放忘れなど)
  3. 並列タスク処理に起因する領域
    (スケジュリングの間違い、排他制御の間違い、共有データ破壊など)
  4. ターゲット移行に起因する領域
    (上記以外のターゲット特有のバグ)

ターゲットマシン上へ移行する前に、これら4つの原因領域全てのバグを可能な限り洗い出し、修正を完了させる。バグの洗い出しは、上記の原因領域「1.」から「4.」の順番で、1つ1つ順に洗い出しを完了させる。それぞれの原因領域で出来るだけバグを洗い出し、修正が完了したら次の原因領域へと進む。例えば、「1.」の計算アルゴリズムに起因するバグを出来るだけ洗い出し、全てのバグを解決した後に、「2.」のメモリ操作処理に起因するバグの洗い出しへと進む。これによって、各原因領域のバグが後段に残らなくなり、もしバグが発生しても必ずその原因領域に起因するバグと決定できるため、バグ原因の特定が容易になる。余分なバグが混ざっていないので、それぞれの原因領域のバグ摘出に労力を集中できるようになる。

それぞれの原因領域に起因するバグを洗い出すには、次に挙げる「1.」から「4.」のような方法で行う。番号は上記の原因領域「1.」から「4.」に対応する。また、各バグ原因領域でバグ摘出/修正する方法/環境を次の表にまとめる。いずれの原因領域に対しても、バグの洗い出しには、事前にテスト/シミュレーションを実施してバグ摘出を徹底させる。

  1. 高級言語を用いてアルゴリズムを実装、単体テストを実施 [D]
    (非ポインタの高級言語を用いてメモリ操作のアスペクトを排除し、アルゴリズム自体の正常動作のみを個別に確認する)
  2. ポインタ言語を用いてメモリ操作を実装、単体テスト/負荷テストを実施
    (ポインタ言語を用いて「1.」を書き換え、メモリ操作を追加実装、メモリ操作に関わるバグを洗い出して修正)
  3. タスクスケジュリングの動作シミュレーション/負荷テストを実施
    (複数のタスクを並列実行、スケジュリングに伴う予期せぬ誤動作を洗い出して修正)
  4. CPUエミュレータで動作検証
    (仮想エミュレータ環境で摘出可能なターゲット移行起因のバグを早期解決)

各バグ原因領域でバグ摘出/修正する方法/環境 [E]

バグの追求フェーズ メモリ操作 並列性 実行環境
[1] 計算アルゴリズム
領域のバグ摘出/修正
非使用
(高級言語)
シングル実行 汎用PCの
言語仮想マシン上
[2] メモリ操作処理
領域のバグ摘出/修正
ポインタ使用
(C/C++)
シングル実行 汎用PC上
[3] 並列タスク処理
領域のバグ摘出/修正
ポインタ使用
(C/C++)
並列実行 汎用PC上
[4] ターゲット移行
領域のバグ摘出/修正
ポインタ使用
(特殊C/C++)
並列実行 汎用PCの
エミュレータ上

原因領域の間で領域範囲が重複しないように、使用言語や実装方法、実行環境を工夫する。例えば、[1]の計算アルゴリズム領域のバグ摘出では、後段のメモリ操作や並列性のアスペクトが混入しないように、非ポインタ言語でシングル実行させてテストを実施する。これによって、[1]では計算アルゴリズムのみに集中できるようになる。

このように、原因領域に分けて段階的にバグ摘出/修正を徹底したことで、ターゲットマシンへ移行する頃には、理想的には前段のバグはない状態になり、[4]のターゲット移行によるバグしか残っていない状態となる。この状態の下で、最後にターゲットマシンへ実装する。作業は実装というよりは単純な移植に近いものになる。理想的には、コンパイルし直して、ターゲットへ転送し、テストを行って終了の形態が望ましい。

しかし、ここまで準備を重ねたにもかかわらず、それでもターゲット移行によるバグが発生することが予想される。それでも発生するバグのために、次のようなコード上の対策を講じ、バグ原因の追求が容易になるようにコードを構築しておく。

  • 関数呼び出しのログ記録機構の組み込み
  • 関数呼び出しのパラメータチェック機構の組み込み
  • システムコールのログ記録機構の組み込み
  • システムコールのパラメータチェック機構の組み込み
  • ログテキストは構造化して読みやすくする
  • メモリ状態を容易に取得でき簡単に理解しやすくする

一方で、前述で述べた対策は、ターゲットマシン上で短期間しかデバッグ/テストできない場合に限らず、その他に次のような場合にも効果を発揮することが期待できる。また、それぞれの場合に応じて、前述の対策を臨機応変に変更することで応用が可能である。

  • ターゲットマシンへデータを転送する転送速度が遅い場合
  • ターゲットマシンが発展途上でバグが多く混入している場合
  • ターゲットマシンに物理的な要因で内部エラーが発生する場合
    (電源不安定、熱影響、内部故障、外乱ノイズ、宇宙空間の放射線など)

------------------------------↓スケッチアップ------------------------------

  • 組込み移行起因のバグとそれ以外の分離
    • 組込み移行起因のバグ以外のバグを全て洗い出して修正を完了しておく戦略
    • バグの発生領域の明確化
      1. 計算アルゴリズムに起因する領域
        (処理方法、計算数式、コード化以前の問題領域)
      2. メモリ操作コードに起因する領域
        (オーバーラン、オーバーフロー、メモリ破壊、解放忘れ)
      3. 並列タスク処理に起因する領域
        (スケジュリングミス、排他制御ミス、共有データ破壊)
      4. 組込み移行に起因する領域
    • バグの発生領域に対する事前テスト/シミュレーションの徹底(下記順)
      1. アルゴリズムの単体テスト
        (アルゴリズム自体の正常動作を個別に確認する)
      2. メモリ操作部分の単体テスト/負荷テスト
        (メモリ操作に関わる隠れたバグを洗い出す)
      3. タスクスケジュリングの動作シミュレーション/負荷テスト
        (スケジュリングに伴う予期せぬ誤動作を洗い出し)
      4. CPUエミュレータで動作検証
        (仮想環境で摘出可能なターゲット移行起因のバグを早期解決)
  • 最後に組込み機器へ実装、というよりは移植に近い
    理想的にはコンパイルし直し→転送→テスト→終了の形態
  • それでも発生するバグのために…
    • 関数呼び出しログ記録機構
    • 関数呼び出しパラメータチェック機構
    • システムコール/上位関数
    • ログテキストは構造化して読みやすくする
    • メモリ状態を容易に取得、簡単に理解しやすくする

これらは、ターゲットが利用できない場合に限らず、転送速度が遅い、ターゲットが発展途上でバグが多く混入/不安定、ターゲットに物理的な要因でエラーが発生する(電源不安定、熱影響、内部故障、外乱ノイズ、放射線etc)、の場合にも同様に有用な手法で、応用が可能。

作成中のレポートVer.4 : すべての文章を書く

上記のレポートは、Word形式でダウンロードできます
(ファイル名 : report_v4.doc)

このように、箇条書きの残りの項目も文章を肉付けして暫定版のレポートを完成させます。レポートVer.3と同じように、箇条書きの内容を文章で肉付けするように説明て、可能であれば箇条書きの項目をそのまま活かします。

[D]のように、必要であれば箇条書きそのものにも、足りない説明を補って項目を肉付けします。また、[E]のように、箇条書きでは表現するのが難しい場合は、積極的にを使用します。箇条書きの項目数が多くなったり、箇条書きの項目に書く文章が長くなる場合にも、表を使った方が表現しやすくなります。

このとき、スケッチアップにある箇条書きのすべての項目を文章にする必要はありません。レポートとしてもう十分であったり、ぼんやりしていて書きにくい項目は、そのままレポートに書かずに放置します。レポートに書かなかった内容も、箇条書きのスケッチアップには残るので、キッパリと諦めて、無駄な労力を掛けないようにします。

残りの項目も肉付けして本文章を完成させる、箇条書きそのものも肉付けした、箇条書きより複雑なら表や図を使う

5. 読み返して修正/完成させる

レポートVer.5を次に示します。レポートVer.4の文章を書いてから1日~2日置いて少し時間を空けた後に、もう一度読み返して、言葉の使い方や文の流れを綺麗に直したレポートです。レポートVer.4から書き足した部分は青色の下線変更した部分は黄色の下線で示してあります。

ターゲットマシン上で短期間しかデバッグ/テストできないので、それまでに出来ることをやっておくといった基本方針を基に対策を講じる。具体的な対策として、開発対象に含まれるバグ全体のうち、ターゲットマシンへの移行によって生じるバグとそれ以外の全てのバグに分離して考え、さらにターゲットマシン上へ移行する前までに、移行起因以外の全てのバグを洗い出して修正を完了させるような戦略を考える。

この例では、開発対象に含まれるバグ原因の領域全体を、次の4項目に分離して考える。

  1. 計算アルゴリズムに起因する領域
    (処理方法の間違い、計算数式の間違い、コード化以前の理論的な問題など)
  2. メモリ操作処理に起因する領域
    (オーバーラン、オーバーフロー、その他メモリ破壊、解放忘れなど)
  3. 並列タスク処理に起因する領域
    (スケジュリングの間違い、排他制御の間違い、共有データ破壊など)
  4. ターゲット移行に起因する領域
    (上記以外のターゲット特有のバグ)

ターゲットマシン上へ移行する前に、これら4つの原因領域全てのバグを可能な限り洗い出し、修正を完了させる。バグの洗い出しは、上記の原因領域[1]から[4]の順番で、1つ1つ順に洗い出しを完了させる方法を採る。それぞれ個別の原因領域で出来る限りバグを洗い出し、修正が全て完了したら次の原因領域へと進む。例えば、[1]の計算アルゴリズムに起因するバグを出来るだけ洗い出し、見つかった全てのバグを解決した後に、[2]のメモリ操作処理に起因するバグの洗い出しへと進む。これによって、各原因領域のバグが後段に送り込まれることがなくなり、もしバグが発生しても必ずその原因領域に起因するバグと絞り込めるため、バグ原因の特定が容易になる。余分なバグが混ざっていないので、余計なことを気にする必要がなくなり、その原因領域のバグ摘出に労力を集中できるようになる。

それぞれの原因領域に起因するバグを洗い出すには、次に挙げる[1]から[4]のような方法で行う。番号は上記の原因領域[1]から[4]に対応する。また、各原因領域でバグ摘出/修正を行う方法/環境を以下の表にまとめる。バグの洗い出しは、いずれの原因領域に対しても、事前にテスト/シミュレーションを実施してバグ摘出を徹底させる。

  1. 高級言語を用いてアルゴリズムを実装、単体テストを実施
    (非ポインタの高級言語を用いてメモリ操作のアスペクトを排除し、アルゴリズム自体の正常動作のみを個別に確認する)
  2. ポインタ言語を用いてメモリ操作を実装、単体テスト/負荷テストを実施
    (ポインタ言語を用いて[1]の実装を書き換え、メモリ操作を追加実装、メモリ操作に関わるバグを洗い出して修正)
  3. タスクスケジュリングの動作シミュレーション/負荷テストを実施
    (複数ある[2]の実装をタスクに割り振り、複数のタスクを並列実行、スケジュリングに伴う予期せぬ誤動作を洗い出して修正)
  4. CPUエミュレータで動作検証
    (仮想エミュレータ環境で実行できるように[3]の実装を書き換え、仮想環境で摘出可能なターゲット移行に起因するバグを事前に解決)

各バグ原因領域でバグ摘出/修正する方法/環境

バグの追求フェーズ メモリ操作 並列性 実行環境
[1] 計算アルゴリズム
領域のバグ摘出/修正
非使用
(高級言語)
シングル実行 汎用PCの
言語仮想マシン上
[2] メモリ操作処理
領域のバグ摘出/修正
ポインタ使用
(C/C++)
シングル実行 汎用PC上
[3] 並列タスク処理
領域のバグ摘出/修正
ポインタ使用
(C/C++)
並列実行 汎用PC上
[4] ターゲット移行
領域のバグ摘出/修正
ポインタ使用
(特殊C/C++)
並列実行 汎用PCの
エミュレータ上

原因領域の間でお互いの領域が重複しないように、使用言語や実装方法、実行環境を工夫する必要がある。例えば、[1]の計算アルゴリズム領域のバグ摘出では、後段のメモリ操作や並列性の領域(アスペクト)が混入しないように、非ポインタ言語でシングル実行するように実装し、テストを実施するように構成する。これによって、[1]では計算アルゴリズムの領域のみに集中できるようになる。

このように、原因領域に分けて段階的にバグ摘出/修正を徹底したことで、ターゲットマシンへ移行する頃には、理想的には前段のバグはない状態になり、[4]のターゲット移行によるバグしか残っていない状態となる。この状態の下で、最後にターゲットマシンへ実装する。作業は実装というよりは単純な移植に近い感覚になる。理想的には、コンパイルし直してターゲットへ転送し、テストを行って終了の形態が望ましい。

しかし、ここまで準備を重ねて来たにもかかわらず、それでもターゲット移行によるバグが発生すると予想される。それでも発生するバグのために、次のようなコード上の対策を講じて、バグ原因の追求が容易になるようにコードを構築しておく。

  • 関数呼び出しのログ記録機構の組み込み
  • 関数呼び出しのパラメータチェック機構の組み込み
  • システムコールのログ記録機構の組み込み
  • システムコールのパラメータチェック機構の組み込み
  • ログテキストは構造化して読みやすくする
  • メモリ状態を容易に取得でき簡単に理解しやすくする

一方で、前述で述べた対策は、ターゲットマシン上で短期間しかデバッグ/テストできない場合に限らず、その他、次のような場合にも効果を発揮することが期待できる。また、それぞれの状況に応じて、前述の対策を臨機応変に変更することで応用が可能である。

  • ターゲットマシンへデータを転送する転送速度が遅い場合
  • ターゲットマシンが発展途上でバグが多く混入している場合
  • ターゲットマシンに物理的な要因で内部エラーが発生する場合
    (電源不安定、熱影響、内部故障、外乱ノイズ、宇宙空間の放射線など)
作成中のレポートVer.5 : 読み返して修正/完成させる

上記のレポートは、Word形式でダウンロードできます
(ファイル名 : report_v5.doc)

このように、日を置いて文章を再読し、細かな表現を修正してレポートを完成させます。上の例で、黄色の下線の部分が修正した箇所です。全体を眺めると、3割程度の文章をここで修正してあります。

レポートが完成して、もういらなくなった箇条書きのスケッチアップは、別のファイルなどに保存してレポートから削除します。スケッチアップには、レポートの基にしたメモ書きや、書かなかった内容が残っているので、完全に消してしまうのではなく、別の場所へ保存しておきます。

日数を置いて本文章を再読し、細かな表現を修正して完成させる、いらなくなった箇条書きのスケッチアップは見えないように隠すか別の場所に保存して本文章から削除する

 

更新履歴
2011/01/14
  • 書き始め
2011/02/05 v1
  • 初版作成

※ご意見、ご感想、改善点、その他の情報などがありましたら、メールにてお知らせ願います。

Copyright (C) 2002 - 2016 Simon.P.G. All Rights Reserved. Top | Simon.P.G. とは | 使用条件 | ご意見
inserted by FC2 system