読者です 読者をやめる 読者になる 読者になる

COBOL技術者の憂鬱

COBOLプログラマは不在にしています

私の仕様書

今週のはてブ人気エントリーに目を通していて、「おっ!」となったのが以下の記事です。


株式会社8bit|モノづくりブログ
個人で作ったWebサービスの仕様書(Evernoteのメモ)を2つ公開してみる - アインシュタインの電話番号☎



乗るしかないこのビッグウェーブに、というわけで私も先日作ったクックパッド人気エントリーの仕様書を晒してみます。
ソースは公開しているんですけど、仕様書は公開していませんでしたね。まぁ仕様書といっても、製作開始前にメモ帳で殴り書きしているだけなので、人前に晒すという発想が今まで出てこなかったのです。



自分の場合、仕様書は、データ設計とプログラム設計の2つに大きく分けて書いています。


まずはデータ設計において、必要なDB(テーブル)とか、その中に定義する項目や更新タイミングを整理します。
実装にあたって疑問点がある場合は、この時点で書いていますね。


○データ設計


・クックパッドDB
 キー:エントリーURL
 データ(はてブから取得):エントリー名称,初回ブクマ日付←初回登録のみ
              ブクマ数
 データ(クックパッドから取得):写真←初回登録のみ
                 カテゴリ1,カテゴリ2,カテゴリ3,つくレポ数,クックパッドからのデータ更新日付


はてブカウンターDB
 キー:なし
 データ:ポインタ



【疑問点】
・写真ってデータストアに入れるのか?
・日付の管理の仕方(DATE型?やったっけ)

プログラム設計ですが、まずは大まかな機能単位でモジュール分割しておいて、それぞれの処理内容について順番に記載しています。
さらに、【作る単位】と称して、細かな機能単位でメソッド分割していますね。そして、それぞれのメソッドについて、そのインターフェースと処理内容について整理しています。
ここでも、この段階で詳細に決めきれない事については、疑問点として挙げています。


○プログラム設計


(モジュール1)はてブからクックパッドのエントリーを抽出して、データストアに登録するスクリプト


はてブカウンターDB取得(ない場合は0を設定)
・クックパッドのドメイン指定で、ブクマ数順、オフセット=はてブカウンターDBの値で取得する
・取得したページをパースして、ブクマ数が5以上のエントリについて、クックパッドDBへ登録あるいは更新する
はてブカウンターDBのポインタに20加算
・取得したページにブクマ数が4以下のエントリが含まれる場合か、エントリがない場合は、はてブカウンタDBのポインタに0を設定する



【作る単位】
(1)はてブカウンターDB取得関数
 INPUT:なし
 OUTPUT:ポインタ
 処理:はてブカウンターDBをGETして、ポインタを返す。ない場合は0をPUTして0を返す。


(2)はてブからページ取得関数
 INPUT:ドメイン名、ソートオーダー、オフセット
 OUTPUT:エントリーURL・名称(文字),初回ブクマ日付(DATE型)、ブクマ数(数値)
 処理:指定されたドメイン名、ソートオーダー、オフセットではてブ検索し、パースして、エントリーURL・名称、初回ブクマ日付、ブクマ数のリストを返す


(3)クックパッドDB更新関数
 INPUT:エントリーURL・名称,初回ブクマ日付、ブクマ数
 OUTPUT:なし
 処理:エントリーURLでクックパッドDBをGETする。
    相手なし時は、PUTする。
    相手あり時は、ブクマ数を比較し、異なっている場合のみPUTする。


(4)はてブカウンターDB更新関数
 INPUT:末尾のはてブ
 OUTPUT:なし
 処理:末尾のはてブ数が5以上の場合、はてブカウンターDBのポインタに20加算。以外は0を設定する。



【疑問点】
どの位のタイミングで更新するべきか?





==========================================
(モジュール2)クックパッドのレシピページを個別に取得して、写真とカテゴリをデータストアに登録するスクリプト


・クックパッドDBを、クックパッドからの更新日付順で1件取得
・取得したURLでクックパッドのページ取得
・取得したページをパースして、クックパッドDBへ登録あるいは更新する



【作る単位】
(1)クックパッドDB取得関数
 INPUT:なし
 OUTPUT:エントリーURL
 処理:クックパッドDBを更新日付の降順に1件GETして、エントリーURLを返す。ない場合はNoneを返す。


(2)クックパッドからページ取得関数
 INPUT:URL
 OUTPUT:写真(型は不確定、単にURLでいけるのか?それともオブジェクトを格納するか?)、カテゴリ1〜3(文字),つくレポ数(数値)
 処理:指定されたURLでクックパッドのレシピを取得し、パースして、写真情報、カテゴリ1〜3,つくレポ数のリストを返す
    存在しない場合はNoneを設定


(3)クックパッドDB更新関数
 INPUT:URL、写真情報、カテゴリ1〜3,つくレポ数
 OUTPUT:なし
 処理:エントリーURLでクックパッドDBをGETする。
    相手なし時は、PUTする。
    相手あり時は、カテゴリ1〜3,つくレポ数を比較し、異なっている場合のみPUTする。



【疑問点】
どの位のタイミングで更新するべきか?





==========================================
(モジュール3)画面表示するスクリプト(カテゴリ別、年代別、季節別/はてブ順、つくレポ数順)


・画面から渡されたパラメータに応じて、クックパッドDBを取得して表示する



【疑問点】
・検索条件指定とかページ指定とかのインターフェースにどの程度こだわるか
・あんまり画面遷移したくない
・シンプルかつエレガントな感じ?
・テンプレートは2chまとめホットエントリーと同じでよいと思う。

後はこの仕様書を見ながら順番に実装していくわけですが、製作中は、これとは別に細かなtodoリストを作成して管理しています。
以下のような内容です。仕様書に挙げきれていない部分で、製作中に必要だと感じた事を一覧にして整理しています。


・新着順表示を追加
・numericcheckをis_numericに変更して、数字のみだったらtrueを返すように変更する。(noneと英字含みはfalse)
・全体にかかっている空文字スキップを削除する
・指定なしもshowparmの中に入れる←保留
・カテゴリ表示順がおかしいので調べる←合ってた
・yearとseasonをまとめる


・ソーシャルボタン
・カテゴリのリンク(マウスオーバーで赤色、それ以外は何もしない)
・タイトルをクリックでパラメータリセット


jqueryセレクトボックス


・ページ遷移
・何が検索されたかわかりやすく


・検索フォーム
 背景に色つける
 フォントサイズ・色
 ボタンの位置

うーん、こんな感じで、人前に晒すつもりのなかったものを晒すのって結構こっ恥ずかしいですねー。頭の中をダイレクトに覗かれてるような感じがして…。
けれども私も、他の方がどんなやり方で開発しているのか結構気になる方なので、個人で開発されている方はどんな形であれ、もっと開発ドキュメントなどを晒していってもらえると嬉しいですね。