羊雲 -5ページ目

<< 前のページへ最新 | 3 | 4 | 5 | 6 | 7 | 最初次のページへ >>

仕様書の書き方３

若手SEのためのシステム設計の考え方―システム企画から要件定義、システム設計書の作成まで

モジュール仕様書について、もう少し詳しく書いておこうかと…。

具体的な構成は以下の様になります。

(1)機能概要
(2)インタフェース仕様
(3)動作仕様
(4)エラーケース
(5)テーブル構造

まあ、こんな感じで、機能概要はそのままですね。インタフェース仕様というのは、この機能を、他の機能ブロックから使った時の入力と出力、呼び出す関数をまとめた物です。これをモノの本では、外部I/F仕様とか言って、別のドキュメントにまとめたりしています。

ところで「外部」ってなんだ～っ！？って気がしません？"外部" からのインタフェースって事なんでしょうが、インタフェースって外部からでしょう。普通。なんか気持ち悪くて、私はこの言葉を使えません。

動作仕様。ここはそのモジュールの動作の仕様を書きます。状態遷移図とか、状態遷移表とか、フローチャートとかを必要に応じて書きます。例えば状態の無いモデルなのに、状態遷移図なんて書けませんよね。あと、フローチャートは細かく書きすぎるとそのままソースコードになってしまうので、あまり詳しく書かなかったりします。でも書かないよりは、書いた方が良いと思います。

エラーケース。異常な処理、他のモジュールのエラー終了とかが返って来た時の振る舞いをまとめます。

テーブル構造は使ってるグローバル変数とか、他のモジュールが参照するテーブルとか、そんなのをまとめたものです。

と、一応これだけ書けば最低限の材料は揃ったって感じなんですよね。本当はここから実際のコードに近付ける為に、定義、定義を繰り返していくのですが、さすがに端折っています。適当にやっていると、仕様書からかけ離れたものがコードとして、生まれてくる事がありますんで、出来るだけその距離が開かない事を意識して書くというのが、必要なのかなぁ…と。そう思います。

んで、最後になりますけど、多分一番重要なのは、なんの為に仕様書を書くのか？残しておくのか？って事を考えて書く事が重要だと思います。それは、顧客の要望を具体的な仕様に定義するための要求仕様書だったり、レビューを行う為の機能仕様書だったり、自分の中で構造や設計をハッキリさせる為の詳細設計書、構造設計書だったりするので、きっと仕様書とは、あるフォーマットにしたがって記述すれば、それなりのものが出来上がるというものでは無いと、今は、感じます。

書き方について語ってきたのに、最終的には、そんなところです…。

・ソフトウェア開発で伸びる人、伸びない人 (技評SE新書002)
・Software people―ソフトウェア開発を成功に導くための情報誌 (Vol.6)

ランチブログロースカツ丼＆焼きそば

オーソドックスながら、うまかったです。

ボリュームに引かれ買ってしまいました。

仕様書の書き方２

Software people―ソフトウェア開発を成功に導くための情報誌 (Vol.3)

仕事でこれしかやってない所為か、ついつい仕様書の書き方について考えてしまいます。今更そんなに必要なのかって意見もあると思います。最近では…というか、かなり前から Case ツールとか、仕様書作成ツールとかの性能が上がってきて、コードから仕様書を吐いたり、UML で書かれたクラス図からコードを吐いたりと、メチャメチャ便利になってます。Visual Studio 2005 も発売される事ですし、なんて言ったって21世紀ですもんね。まったく。

でも、なんで私がそんな事をやってるのかと言うと、そういうツールが高くて買えないというわけではなく、結局そういう話ってハイエンドのシステム開発 SE のお仕事だったりするわけですよ。Java とか Visual C++ とかその辺の Windows アプリ。私の様な SE 界の雑草の様な、組み込みエンジニアからはちょっと遠い話なのです。(あ、別に組み込みエンジニアリングを愚弄しているわけでは無いです。なんだかんだ言っても私はこの仕事に誇りを持っています)

さて、前置きが長くなってしまいました。ちょっとノッて来たので、仕様書、設計書に具体的に何を書いたらいいのか、という話をしようと思います。

私が書いている仕様書の種類は以下の様になっています。

(1)基本設計書
(2)システム構成図
(3)モジュール仕様書

基本設計書はシステム全体で、どんな機能ブロックがあって、どんな構造になっていて、それぞれの構成なんかをざっくりと書いています。あと OS の共通 API なんかはここでまとめてしまいます。

システム構成図では、文字通り"図"で、タスクとメッセージ(キューとか)のつながりを書きます。タスクには優先度とかを記述し、図を見るだけで、まあ、モジュール構成の矛盾が無いかどうかを確認します。１つのキューから２つ以上のタスクが、メッセージを取ってたり、１つ前のタスクの方が優先度が高い時などは注意が必要です。

で、モジュール仕様書。これは機能ブロックごとの仕様を、それなりに突っ込んで書きます。状態遷移図・表、フローチャートとかを使って、その機能が、ちゃんと動くモデルであるという事を書きます。あと他の機能ブロックからのインタフェース（入力と出力とグローバル関数）なんかもここに書きます。ちなみにクラスの場合もここ。

まぁ、ざっくりとそんな感じなのですが、いろいろ流儀があるらしく、仕事でいろいろ調べてみたら、結構、楽しめました。…と、ドキュメント作りにどっぷりと浸かってしまって、最近コードを書いていません…。コードを書いている時が一番楽しいのですけどね…。

仕様書の書き方３へ続く

・管理者になったとき困らない実践的ソフトウェア開発工程管理
・図解でわかるソフトウェア開発のすべて―構造化手法からオブジェクト指向まで

ランチブログごはん亭炙りチャーシュー丼

とまぁ、そんなわけで、様子見ながらランチブログです。

いや、美味かったですよ。炙りチャーシュー丼。さすがローソン、ごはん亭ですね。

量も十分、ご飯は麦ご飯で満足の一品でした。

オーガニックフェスタ行ってきました

去年も行ったのですが、ここで買ったワインとピクルスが気に入ってしまいまして。あと豆ご飯を去年買ったのですが、食べずに古くさせてしまい、今年はリベンジも兼ねて。

ワインはかなり気に入ったヤツがあるのですが、普段売ってるお店の場所も分からなかったので、今回はちゃんとお店の場所を聞いてきました。ただ、ちょっと分かりづらい場所にあるらしく、出不精の私が行く気になるか心配です。

オーガニックフェスタ自体は去年とさほど変わらず、規模はちょっと大きくなったかもしれませんが、今後に期待されるところでした。いろいろイベントやってるみたいでしたけれど、市場しか行かず…、しかも目当ての３品ゲットして普通に帰ってきました。もう少し色々周り安かったらなぁと思います。

自然食サイコーッ、ウマーッとか、食に妥協しませんとか、言ってる私ですが、学生の頃はコーラとタバコしか口にしていませんでした。人間変われば変わるものですねー。

ドキュメントについて

えーっと、機能に引き続いて仕様書の書き方です。

実は私が一番気になるのはフォントです。私が何かしらのドキュメントを書くときは、フォントはＭＳゴシック（日本語）、Arial（英語）を基本に使っていて、ソースコードとかを貼り付けたりする時は、半角のＭＳゴシックを使うと…。

なんでそういう事をするのかというと、読みやすくして読んでもらう為なんですよ。ブラウザで見ている文章の殆どは、ＭＳゴシックなので見慣れてるから可読性は高いかなと…。あと縮小したり、斜体にしたりした時でも、かなり可読性の高いフォントなのですよ。

まぁ、そんな感じで、それなりに、字さえにも気を使ってるのですが、これがまた悩みの種で、人の書いたドキュメントって殆ど Word のデフォルトで書かれているのです。フォントはＭＳ明朝＋Century で、もう、字の隅の方がひんまがってて、ホント読みづらいのですが…。私だけでしょうか？しかも私の書きたい内容とちょっと同じ様な事が書かれているから、コピーしようなんて思った日には、私のフォントに統一性の取れたドキュメントに、にっくきＭＳ明朝＋Century フォントの文章が、そのままベターッとくっ付くのです。

これはもう、ヒーッて感じなので、一生懸命貼り付けた文章のフォントをＭＳゴシック＋Arial に書き直すのです。

まぁね…。良いのですよ。デフォルトのままってのも…。面倒でしょうし…。もしかしたら見にくいと思っているのは私だけかもしれませんし…。でもね。これだけは勘弁して下さい。

ソースコード貼り付ける時に Century 使うのやめて下さい。

もう、インデントとか変数名とかぐちゃぐちゃです。だって、Century でプログラムしてないでしょ？ゴシックでしょ？なんでドキュメント書く時だけ、Century なんですか？もう、面倒でフォント変えてられないか、そもそもドキュメント書く気が無いとしか思えませんよ。

…と言いつつこのブログはＭＳＵＩゴシックという、また、違うフォントで書いています…。

仕様書の書き方

管理者になったとき困らない実践的ソフトウェア開発工程管理

さて、この１週間何が忙しかったのかと言うと、かなりの量のドキュメントを書いていたので、連日晩くまで、仕事をしてしまい、なかなか家にも帰れず、ブログも書けずな毎日でした。こっそり会社からブログを更新する事もできるのですが、さすがにそんな余裕もありませんでしたよ…。

はぁ…。

何を書いていたのかというと、プログラムの設計仕様書なのですが、これがまた書くのに苦労するんです。詳細であれば良いってもんでもないですし…、最近はデザインレビューと言って、チームのみんなで確認し、チェックする様な体制に遅ればせながら、ウチの会社もなって来ましたので、こう、他人が見ても理解がしやすく、かつ、私のイメージを伝え、飽きさせないような資料にしなければなりません。これが、なかなか難しいのです。

教科書通りに書いてしまうとなんか項目を埋めただけの様な、味も素っ気も無いドキュメントになってしまいますし、適当にさっぴくとレビューの必要性が薄れると…。絶妙なバランスが必要なんですね。

で、何枚も何枚も書いて気が付いたのですが、結局ドキュメントに書かなければいけない事ってのは、自分が知りたい事、という考えに至りました。なんとなく客観的にみて、自分が書きたい事ではなく、知りたい事を意識してまとめてみると、それなりに自分で納得できる形になりました。

新人さん達のドキュメントを見ると、どうも迷いみたいな物が見え隠れしていて、この辺の感覚がまだまだのような気がします。なんかそういう事を伝えて行けたらなぁと思う今日この頃です。

仕様書の書き方２へ続く

・Software people―ソフトウェア開発を成功に導くための情報誌 (Vol.5)