こんにちは、組み込みエンジニア歴20年以上のtomozoです。
今回は、
組み込み開発の設計書/仕様書
について徹底解説します。
この記事は
- 仕様書って何をどう書けばいいのだろうって考えている新人組み込みエンジニアの方
- あまり設計書や仕様書を書いていない組み込みエンジニアの方
向けの記事です。
設計書もプログラミングも同じで
しっかりと書き方・書くべきことを学んで、
何度も書いていけば良いドキュメントが書けるようになります。
しかし、開発の現場では設計書をしっかり書けない・書かない人が多いです。
それは周りの環境や会社の文化が大きいです。
きちんと書ける人が多い会社で育ったエンジニアは
きちんと書けるようになりますが、そうでない場合
全然書けないもしくは自分よがりな設計書を書く人になってしまいます。
設計書は非常に重要なので、しっかりと書けるようになっておけば
エンジニアとしても一目置かれるようになりますよ。
この記事を読めば
- 組み込み開発の設計書について
- 設計書のメリット・デメリット
が分かるようになります。
それでは早速解説をはじめます。
目次
組み込み開発の設計書の種類と開発の流れ
新人エンジニアあん
組み込み開発の仕様書は一般的に以下の3つに分類されます。
- 要求仕様書
- 基本設計書
- 詳細設計書
組み込みソフトウェアの開発はV字モデルとウォーターフォールモデルと
呼ばれる以下のような流れになっています。
- 要求分析
- 要件定義
- 基本設計
- 詳細設計
- プログラミング(コーディング)
- コードレビュー
- 単体テスト
- 結合テスト
- システムテスト
- 受け入れテスト
図.V字モデル
図に書いたようにプログラミングまでの各工程と各テスト工程が
横軸で対になっているのが特徴です。
ところが実際の開発現場ではなかなかできていないところもあります。
設計書をきちんと書かない
ベテランエンジニアは頭の中で必要なソフトウェア構成がイメージできる場合
設計時のメモに自分が分かる要点だけ書いて
いきなりコーディングを始めてしまったりします。
このメモを設計資料と言ったりするベテランエンジニアもいるのですが、
たいてい第三者が見ると全然意味が分からなかったりします。
設計書はあるほうがいいのは頭ではわかっているのですが、
無くても開発がすすめられることが増えてくるにつれて
書かなくなってきます。
設計書を書く時間が十分でない
現在は開発競争の激化、製品の複雑化・高性能化により
コーディングとデバッグ工数が増えています。
組み込みエンジニアはコーディングして
組み込み機器の試作テストを早く求められるため
じっくり設計書を書く時間がとれないという現場の実態があります。
各設計書に書くこと
各設計書に書くことと開発工程の説明をします。
要求仕様書/要件定義工程
要件定義工程ではこれから作る組み込み機器に対して
以下のようなことを仕様書に記載します。
- こんなものを作りたい
- こんなことがしたい(機能・非機能)
- 予算はどれくらい？
- 開発工数や開発体制をどうするか？
など
具体的な実現方法などは記載しません。
なお要求元は営業部門や客先などです。
要求元や社内の関係者との認識を合わせるために
要求仕様書を作成します。
組み込みエンジニアが作成する場合もありますが、
プロジェクトリーダーや営業・企画職の方などが
書類の大半を作成することが多いです。
基本設計書/基本設計工程
基本設計書は組み込みエンジニアが作成します。
記載する内容としては
要求仕様の中にある機能要件について
具体的に実現する方法です。
一例をあげると
- ハードウェアは何を採用しどう構成するか
- マイコンの機能は何を採用しをどうするか
などを記載します。
詳細設計書/詳細設計工程
詳細設計書は組み込みエンジニアが作成します。
記載する内容としては
基本設計書の内容をさらに細かく設計した内容です。
例えば、使うマイコンの機能の詳細な設定・設計内容などを記載します。
この詳細設計に従ってプログラミング(コーディング）を
進めて行くのでプログラムの解説書ということもできます。
これら３種類の設計書を簡単な一例で説明すると
- 要求仕様書 ⇒ 時計機能
- 基本設計書 ⇒ マイコンは○○を使用しタイマー機能を利用
- 詳細設計書 ⇒ タイマーAを使ってXXの設定でYYをカウントし時計を表示する
というような感じで記載します。
実際はもっと具体的に書く必要があります。
なお基本設計書と詳細設計書が一まとめになっている場合もあります。
設計書を書いたことがない人はコーディングを始める前に
こういった設計書が必要だということを
覚えておいてください。
設計書を書くメリット
新人エンジニアあん
tomozo
（開発前）プログラミングを進めやすい
プログラミングの前にしっかりと考えて設計書を書いておけば
その通りにプログラミングを進めて行くことができます。
頭で考えて設計しながらプログラミングを行うと、
手戻りが発生したりして効率がよくありません。
また、プログラミングの前に自分以外の人と設計書でレビューをしておけば
品質を高めて、設計の欠陥や配慮漏れを未然に見つけられる可能性もあります。
（開発中）自分以外の人が理解をしやすくなる
業務都合などによって、その機器のプログラマーがずっと自分とは限りません。
部署の異動であったり、他のプロジェクトの関係で
途中から他の人が代わりに担当することがあります。
そんな時に作った本人しか分からないような
読みづらいプログラムだけしかないと
引き継いで担当する人が非常に苦労します。
分かりやすい設計書があればスムーズに引継ぎを行えます。
引継ぎ以外でも、開発が遅れて他の人に手助けしてもらうこともあります。
こんな時も設計書があれば、フォローしてもらう部分を
素早く理解してもらうことができます。
（開発後）保守・改編などで見返す時に思い出しやすい
プログラムを作ったあと時間が経ってから
仕様変更、モデルチェンジ、不具合が見つかって修正
なんてことはよくあります。
作った時は分かりやすいプログラムを作ったつもりでも
時間が経ってから見返すとなぜこういう風に作っているのだろうとか
この数字はどこから出てきたんだろうってことがあります。
半年も経てば、自分の書いたプログラムでも他人が書いたように
見えるものです。
こういったこと防ぐために設計書をしっかりと書いておけば
後々思い出すのにとても役に立ちます。
設計書を書くデメリット
新人エンジニアあん
tomozo
開発工数が増える
経験が豊富で頭のいい人や簡単な要求仕様であれば、
構想のメモを書く程度でコーディングを始めることができます。
こういう場合、わざわざ設計書を書かずにコーディングを始めたほうが
最短でモノを動かすことができます。
趣味のモノ、プロトタイプ限定と割り切ったモノ、
確実に自分一人しかプログラミングしないモノ
などであればこれでも問題ありませんが、
製品化していくモノ、自分以外の人が触る可能性のある会社のモノであれば
上述のメリットがある設計書を書くべきです。
しかし、設計書を書くにはプログラミングと同じくらいの時間が必要になります。
tomozo
開発日程を計画する時に設計書を書く時間を盛り込んでいない場合は、
自分から工数を取ってもらうように相談しましょう。
短納期化で設計書を書くと優先度が低くなり、
作法無視の “ごった煮”で使えない設計書になりがちなので注意しましょう。
こんな設計書がいい
設計書を書く上で注意してほしいことは以下の点です。
- 必要な情報が網羅されている
- どこに何が書いてあるのか分かりやすい
- 読みやすい言葉で書かれている、フォームやフォントなど体裁が整っている
設計書はワードとエクセルどちらでもいいですが、
見出しを使って検索しやすくしたり、
目次からのリンクを付けておくことをお勧めします。
印刷するならワード、図や表を多用するならエクセルのほうが書きやすいです。
tomozo
ワードやエクセルなどのオフィス系のアプリケーション以外にも
組み込みエンジニアしか読まないのであれば、
マークダウンなどの形式で書く場合もあります。
マークダウンで書くと、変更履歴を管理しやすいバージョン管理ツールを使うことができます。
ワードやエクセルだと変更履歴も漏らさず自分で記載しないと
変えたところが分からないですからね。
gitを使ってプログラムを作ったことがあるエンジニアの方には
理解してもらえるのではないでしょうか？
ツールは手段に過ぎないので周りの環境に合わせればいいですが、
何より大切なのは読みやすい・読める設計書を書くことです。
こんな設計書はダメ
以下のような設計書を書かないように注意しましょう。
- ソースコードと設計書が一致しない
- 読みにくい
- 「意思決定がなされた根拠」が抜け落ちている
ソースコードと設計書が一致しない
メンテナンスされていない設計書は
ソースコードと設計書のどちらが正しいのか判断がつかず
混乱の種になります。
設計書がメンテナンスされないのは
設計書→コーディング→デバッグ→プログラム修正→デバッグ→プログラム修正・・・
という開発の流れになりプログラム修正により設計当初とプログラムが変わってくるためです。
プログラムを変えたときに設計書を書き換えればいいのですが、
たいてい時間の余裕がはありません。
そんな時はある落ち着いたタイミングで設計書をメンテナンスして
後追いでもプログラムと一致するものを必ず残すようにしましょう。
読みにくい
読みにくい設計書の例を挙げると
- 文章がおかしい、一読しただけでは意味が分からない
- 文字ばかり
- 文章による説明が全くなく図や絵しかない
- 作成した本人しかわからない用語が数字が使われている
などが挙げられます。
エンジニアは国語が苦手な人も多いので意識して文章力も上げて行きましょう。
自分で音読したり、先輩や上司に読んでもらうことでかなり改善できます。
また絵を書くと時間がかかるので文字ばかりになったり、
絵や図を書くのに時間をかけて文章がおろそかになったりします。
何より読み手を考えて書くという意識を持つことが重要です。
読み手は自分だけなのか、ソフト屋だけなのか、
開発チームだけなのか、エンジニア以外も読むのか
読み手によってどの程度の詳しさが必要なのかも変わってきます。
「意思決定がなされた根拠」が抜け落ちている
組み込み機器のプログラムには実験の結果や設計値などから
特定の時間や定数を使うことがよくあります。
なぜその数値になったのかは残しておかないと
後々関連個所のプログラムを変更するとき困ります。
また複雑な制御・アルゴリズムを使用しているのに
なぜそうしたのが経緯や根拠が全くない。
こういった内容は、会社の資産・知的財産です。
しっかりと根拠も設計書に残すようにしましょう。
まとめ
設計書の種類と書くべきこと
- 要求仕様書：何を作るのか
- 基本設計書：要求を満たすためにどういった組み込みシステムにするのか
- 詳細設計書：基本設計書を見ればプログラムできるようにする
設計書を書くメリット
- （開発前）プログラミングを進めやすい
- （開発中）自分以外の人が理解をしやすくなる
- （開発後）保守・改編などで見返す時に思い出しやすい
設計書を書くデメリット
- 開発工数が増える
良い設計書
- 必要な情報が網羅されている
- どこに何が書いてあるのか分かる
- 読みやすい
悪い設計書
- ソースコードと一致しない
- 読みにくい
- 「意思決定がなされた根拠」が抜け落ちている
参考になったとか、もっとここが知りたいなど一言でも
コメント、意見などいただけると励みになります。
こちらの記事でマイコンの基本機能についてまとめています。
もしよければご覧ください。
マイコン基本機能5選【初心者組み込みエンジニア必見】
このサイトでは
学校や友人、親は教えてくれない
資産運用についても紹介しています。
できるだけ早く自分の将来のために勉強しておかないと
もっと早く知っておけば良かったって後悔しますよ。
インデックス投資はおすすめ!厳選ファンド(商品)3つと利回り検証
