プログラマが欲しい仕様書とは

プログラマが欲しい仕様書とは

東京開発グループリードソフトウェアエンジニア

牧野克俊

ソフトウェア工学って知ってますか？

ソフトウェア工学とは

• ソフトウェアの開発・運用・保守について体系化、分析、研究する分野

• 高度で安全なソフトウェアを短期間で設計するための研究を行う

• 知っていると役に立つのは–ソフトウェア開発工程–ソフトウェア開発方法論

ソフトウェアの開発工程

ソフトウェアの開発工程• 要求分析• 設計• コーディング• テスト• 運用・保守


• 要求分析– ソフトウェアがどのような機能を持つべきか

を検討し文書化する。


• 設計– 機能がソフトウェアとしてどのように実装さ

れるべきかを検討し仕様化する。


• コーディング– 仕様に従ってプログラムを作成する。


• テスト– 作成されたプログラムが機能的な要求を満た

していることを実証する。


• 運用・保守– ソフトウェアを使用したり、新たな要求に応

じて機能を追加・変更する。

一般的に必要とされるドキュメント

必要とされるドキュメント• 企画書• 要求仕様書• 設計書• 機能仕様書• 詳細仕様書• テスト仕様書• 運用マニュアル

ドキュメントはなぜ必要か？

ドキュメントはなぜ必要か？

• 効率よく開発するため–情報共有するため–思考をトラッキングできるようにする

ため–質問を減らすため

コラム：情報共有とは• 「教育の情報化と情報セキュリティ」

より–機密性 (confidentiality)

• 認可されたものだけが情報にアクセスできること–完全性 (integrity)

• 正確であること、及び完全であることを維持すること–可用性 (availability)

• 許可されたものが必要なときに情報にアクセスすることが可能であること

コラム：情報共有とは

• 必要な人がいつでも自由に、正しい情報を取得できるようにすること

ゲーム制作に最低限必要なドキュメントは？

最低限必要なドキュメント1. 企画書2. 機能仕様書3. 運用マニュアル

1. 企画書• タイトル、プラットフォーム、コンセプ

ト、売り、ゲームシステム、キャラクターなどの説明

• １枚目からラストにかけて、流しても読めるような企画書が望ましい

• 一番重要なのは『何かが面白い』『遊んでみたい』『売れそう』という３点

2. 機能仕様書• ユーザの観点からゲームがどのように動

くか記述する• どのように実装されるかは問題にしない• 機能を中心としており、用語の定義とか、

UI とかいったものの仕様も定める

3. 運用マニュアル

• システムの構築方法• 操作方法や注意点• トラブル発生時の対処法

プログラマが欲しい仕様書はどれ？

機能仕様書です！

プログラマが仕様書を欲しがる理由は？

ソフトウェアデザインをするため！

ソフトウェアデザインとは

• プログラムを機能単位に分割し、構造化したり処理の流れを決める

コラム：良いプログラマの生態

• リファクタリングは苦にならないが、仕様変更による作りなおしは嫌がる

• 心配性もしくは細かいことを気にする

どんな機能仕様書を書けばいいか？

最低限必要な項目• シナリオ• 対象外• 概要• 詳細• 未解決の問題• 用語解説

シナリオ

• ターゲットは？• どのような状況で使うのか？• どのように使うか？

対象外

• 明らかにオーバースペックなこと• 今のバージョンでやらないこと• 対象外のプラットフォーム

概要

• 一覧性が重要• 全体像を把握させる–フローチャート–関係性

詳細

• 想定される状況を全て書く• 何がエラーになるか全て書く• 全てのエラーに対してどう処理する

か書く

未解決の問題

• 何が未解決か残す• これが残っているうちはプログラマ

にコードを書かせない

用語解説

• 一般的な単語でもドキュメント中での意味を書く

仕様書のアンチパターン1. 同一レイヤの事を書いてるのに人によってフォーマットがば

らばら2. 一見似ているがよく見ると若干違う情報があちこちにある3. できないこと、やらなくていいことが書かれていない4. 単語、言い回しが統一されていない5. 値の範囲が書かれていない、単位が統一されていない6. 実現すべきことが書かれていないのに詳細なロジックだけ書

いてある7. 語尾が「～したい」で終わっている8. 変更があっても更新されない9. プログラマに相談、確認がされていないことがある10. わからないことがあったら直接聞いてくださいと書いてある

1. 同一レイヤの事を書いてるのに人によってフォーマットがばらばら

• 絶対に必要な項目を抽出する作業が必要–テンプレートを作りましょう

2. 一見似ているがよく見ると若干違う情報があちこちにある

• 仕様書の構造を見直しましょう–共通部分を切り分ける–機能の関係性が分かるように

3. できないこと、やらなくていいことが書かれていない

• これらはプログラムの設計に影響する–どんなエラーが起こり得るか？–その時どうするか？–何が必要ないか？

4. 単語、言い回しが統一されていない

• 用語集は必須– ないと絶対誤解します！

• 言い切り言葉でしめる–例• ☓ ザコをすべて倒すことで、ボスと戦うことがで

きます（できるようになります）• ○ザコを全て倒すと、ボス戦に移行します

5. 値の範囲が書かれていない、単位が統一されていない

• 値には必ず取り得る範囲を決める–無限は実現不可能

• 精度を気にする– [0－ 1000] の値を取る時、小数点何位まで比較するか

• 数値を書く場合は常に単位を書く–秒なのかミリ秒なのかはっきりと

6. 実現すべきことが書かれていないのに詳細なロジックだけ書いてある

• プログラマが知りたいのは実現すべきこと– ロジックはプログラマに考えさせるのが

Better

7. 語尾が「～したい」で終わっている

• 仕様書には実装すべきことだけを書く–ボリュームの調整はスケジュールを組む段階でする

8. 変更があっても更新されない

• こまめに更新•相談したら即反映

9. プログラマに相談、確認がされていないことがある

• 仕様書を書いたら絶対プログラマのチェックを入れる– フローがおかしくないか– データ構造に無駄がないか– ロジックがもっとシンプルにならないか

10. わからないことがあったら直接聞いてくださいと書いてある

• これは記述が足りないということ• 仕様書は誰が読んでも誤解なく理解

できるように書くべき

プログラマが欲しい仕様書とは

Technology