アプリの設計ドキュメントに関する考察 - りんご嫌いな「iPhoneアプリディベロッパ」のつぶやき

　iPhoneアプリ開発において、コードを書く前に頭の中だけで構想くらいはしますが、今までドキュメントは書かずに「なんとなく」でコードを書いていました。画面数もそう多くなく、自分しか作らないし、頭の中で整理できると思っていたからです。
　それに仕事では、誰も見ない読まないであろう無駄な納品ドキュメントを散々書いてきた経験もあり、無駄なドキュメントは極力書きたくないと言う思いもあったのです。

　しかし、（一定のルールは設けつつも）場当たり的にクラス名やメソッド名を決めたり、コードを書いていると（特に日数が経過すると）、結局ソースコードを見ないと何もわからない状態になりつつあります。

　それだと生産性が低い上にそのうち整理しきれなくなると思い、やはり今更ながら改めてドキュメントの重要性を認識しました。そして、

「自分以外の他のディベロッパはどうやってiPhoneアプリの設計・開発しているのか？」

　と思い至り、設計しやすいドキュメントのサンプルでもないものかと探してみたものの見つけられませんでした。といっても全くなかったわけではなく、画面イメージのイラストを描いて、

「iPhoneの画面上でこうやったらこうなる」

程度のものでした。よほど複雑なUIを実現するのでもなければ、そのレベルならさほどドキュメント化は必要ないと思います。（もちろん書いて損になることはないと思いますが）

　私が欲しかったのは、たとえばUIView系クラスなら、どのデリゲートメソッドに何を処理させて、ユーザメソッドを定義するならその定義と処理の概要、あとはタップ等に反応するアクションとメソッドのひもづけ等です。

　もしInterface Builder（以下IB）を使っていれば、アクションとメソッドの紐づけはxibファイルを見ればわかるかもしれませんが、それにしても画面ごとになってしまい、ソースコードを見るのとあまり変わらない気がします。
　
　AppleがSDKやフレームワークを提供している以上、ある程度参考になる開発プロセスとドキュメントをAppleから提供してもらえたら一番いいのではないかと思い、英語でも検索しましたが、局所的な技術情報しか見当たらず、開発プロセス全体を見渡した手法みたいなものはありませんでした。

　つまり、ウォーターフォールモデルでいえば、提案書や要件定義レベルでのドキュメントの書き方は見つかったものの、それ以降の詳細設計やプログラム設計はなかったことになります。

　私みたいな初心者はともかく、アプリをいくつもリリースしているベンダやディベロッパの方はおそらく独自の開発プロセスを確立しているんだろうと思います。だから本来であれば開発プロセスやドキュメントを自分で確立しなければいけないと思いますが、技術情報と同じで、モデルとなるものがあるとみんな幸せになれるのになあと思いました。

　というわけで、とりあえず自分用にエクセルでフォーマットを作り始めてみました。以下が概要です。

１）プロジェクト全体の情報

・シート間共通情報

1. プロジェクト名
2. 概要

・概要シート

1. 画面リスト（各画面のクラス名と概要）
2. プロパティファイル（プロパティファイルを使用する場合のファイル名と概要、目的。ハンドラクラスを作るならそのクラス名）
3. ローカライズ（多言語対応する場合の言語名）
4. フレームワーク（使用するフレームワーク）

２）UIView系クラスの詳細

・シート間共通情報

1. プロジェクト名
2. クラス名
3. 基底クラス
4. 概要

・概要シート

1. インポート（クラス・またはヘッダ名、その役割）
2. デリゲートクラス（クラス名、役割）
3. 簡単な画面イメージ（イメージがわかる程度であんまり細かく作りこむ必要なし）

・フィールドシート

1. フィールド（型、フィールド名、あれば初期化値）
2. プロパティ（型、プロパティ名、内容）

・メソッドシート

1. デリゲートメソッド（メソッド名、デリゲートクラス名、処理概要）
2. オーバーライドメソッド（メソッド名、基底クラス名、処理概要）
3. ユーザメソッド（メソッド名、戻り値、概要、引数リスト（名前、型、役割））

・アクションシート

1. アクション（アクション名、アクション発生オブジェクト、対応メソッド、概要）

３）プロパティファイルの詳細

・シート間共通情報

1. プロジェクト名
2. 概要
3. プロパティファイル名
4. ハンドラクラス名
5. ファイル種別

・ファイル概要シート

1. 第１階層の項目名、属性、役割
2. 第２階層の項目名、属性、役割
3. 第３階層の項目名、属性、役割

・ハンドラクラス概要シート

1. インポート（クラス・またはヘッダ名、その役割）
2. デリゲートクラス（クラス名、役割）

・ハンドラクラスフィールドシート

1. フィールド（型、フィールド名、あれば初期化値）
2. プロパティ（型、プロパティ名、内容）

・ハンドラクラスメソッドシート

1. デリゲートメソッド（メソッド名、デリゲートクラス名、処理概要）
2. オーバーライドメソッド（メソッド名、基底クラス名、処理概要）
3. ユーザメソッド（メソッド名、戻り値、概要、引数リスト（名前、型、役割））

・静的・初期ファイル内容シート

1. 第１階層の項目名、内容
2. 第２階層の項目名、内容
3. 第３階層の項目名、内容

　とりあえず目下必要そうな箇所だけを抜き出してみたものの、結構な項目数になりました。やはりドキュメントは書くべきなんだと思いました。　
　少しだけ解説しておきます。「３）プロパティファイルの詳細」にて、ハンドラクラスの記述があります。プロパティファイルへのアクセスを取りまとめるクラスを作成する場合に、その定義を書く場所です。ハンドラクラスを作らない場合もあるかも知れませんので、その場合はこれらのシートは使わないことになります。

　そして「静的・初期ファイル内容シート」ですが、これはアプリ固有の情報を定義する場合に、その設定情報は不変となる場合が多いと思います。可変であったとしても初期値がある場合、その場合のファイルの内容を定義します。実際のファイルを見れば内容はわかるので、このシートの重要性はそこまで高くはないと思っています。

　私の場合、まだまだiPhoneSDKをわかっていないため、やろうと思っている事が出来るか出来ないかをコードを書きながら把握していきます。しかも画面単位にスパイラル、インクリメンタルに開発することが多いので、最初からバーっとこれらドキュメント全部を書くことはないと思います。

　このドキュメント群は、あくまで目的が「自分のiPhoneアプリ開発用」なのでチーム開発には向かない、自己満足に陥っている可能性もあります。

　それと書いていくうちに足りない項目や変えたい項目は出てくると思いますので、とりあえずこれで運用を開始して随時変えていって、ある程度のレベルになったら公開したいと思います。