関数仕様書の話

本文(発行内容)

＜関数仕様書の話＞
どうも、三流プログラマーのＫｅｎ３です。

今回は、
関数仕様書について、軽く書きたいと思います。

たいした解説、回答内容じゃないのですが。

/*
 * １．今回のキッカケ
*/

----
 >関数仕様書の書き方についてご教授ください。
----
と
質問のメールをもらった。

三流プログラマー的回答なので、
いつもの部分参考でヨロシクです。
~~~~~~~~~~~~~~~~
えっ、今日は一部でも参考になるのかよ？
最近キツイなぁ、読者の声が、
^^^^^^^^^^^^^^^^^^^^^^^^^^^
参考にならなかった、読んで損したにならないように、１つはヒットを目指して。

/*
 * ２．関数仕様書かぁ、、ＨＥＬＰと同じ書式でいいんじゃない？
*/

メールアドレスが女性読者の会社からぽかったけど（.co.jp）
冷たく、下記のように短い回答でした。
※あれ？めずらしいねぇ、女性には優しいのにね。

VBAのヘルプと同じでいいんじゃない？
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
下記、Excel2002のHELP Dir関数です

Dir 関数
^^^^^^^^ と、関数名があって

>指定したパターンやファイル属性と一致するファイルまたはフォルダの名前を表す
>文字列型 (String) の値を返します。ドライブのボリューム ラベルも取得できます。

↑簡単な（簡潔な）機能説明があり

構文
>Dir[(pathname[, attributes])]

↑と、コールの方法が載っていて、
↓あとは、パラメータ、引数の説明、定数、戻り値の説明があれば

>Dir 関数の構文は、次の指定項目から構成されます。
>
>指定項目 内容 
>pathname 省略可能です。ファイル名を表す文字列式を指定します。フォルダ名
>およびドライブ名も含めて指定できます。引数 pathname に指定した内容が見つ
>からないときは、長さ 0 の文字列 (" ") を返します。 
>attributes 省略可能です。取得するファイルが持つ属性の値の合計を表す数式ま
>たは定数を指定します。省略すると、標準ファイルの属性になります。 

設定値

>引数 attributes の設定値は次のとおりです。
>
>定数 値 内容 
>vbNormal 0 標準ファイル 
>vbReadOnly 1 読み取り専用ファイル 
>vbHidden 2 隠しファイル 
>vbSystem 4 システム ファイル。Macintosh では使用できません。 
>vbVolume 8 ボリューム ラベル。この値を指定すると、すべての属性は無効に
>なります。Macintosh では使用できません。 
>vbDirectory 16 フォルダ 
>vbAlias 64 エイリアス ファイル。Macintosh でのみ使用できます。 

あとは、下記のような詳細の解説や注意事項があってもいいし。

>解説
>
>Windows の場合、複数のファイルを指定するための "*" (アスタリスク) 
>および "?" (疑問符) のワイルドカード文字を使用できます。Macintosh の場合、
>これらの文字は有効なファイル名の文字として扱われるため、このワイルドカード
>文字を使用して複数ファイルを指定することはできません。

なんて、冷たい回答でした。







/*
 * ３．堅苦しくなく、わかればいいのかなぁ
*/

ヘルプと同じ、まぁ、無難な答えだよね。
逆の言い方だと三流プログラマーらしくないよね、そんな優等生的な回答は（笑）

オレも期待してないし、読者も期待してないよそんな回答は。
そうですか、最近、クレーム無いように安全にやってるんだけど。

仕様書は、何のために書く？
・もちろん、納品書類の厚さ稼ぎですよ（あとで誰も見ない／読まないけど）
・作業依頼の時の資料ですよ／作成時の資料
・自己満足ですよ
いろいろと考えられますが、

多くは、他の人とのやり取りのために、仕様書を作成すると思います。
※カッコつけて、未来の自分への手紙と書いてもいいけど、
　たぶん、自分の書いた仕様書を未来の自分は読まないと思う。
　現実は、未来の被害者（担当者）が読む可能性はあるけど。

実は、紙にぐちゃぐちゃ多く書き込むより、
関数の作成依頼なら、
^^^^^^^^^^^^^^^^^^^^
Sub Test_Main()

    Dim strA As String

    strA = getF()  'フォルダーの名前を返す、
    MsgBox strA

End Sub

なんて、書いて、
関数内でフォルダーを選択するダイアログを表示して、
フォルダーの選択、選択された値を返してね。
と言った方が、作成者にイメージが伝わりやすかったと思う。

あと、たまたまだけど、使用する上位モジュールのサンプルをつけているので、
依頼された関数の作成者側は、それで作成したモジュールのテストも出来て、
やりやすかった。

サスガに、
納品書類で、呼び出す上位側のモジュールと簡単な機能説明だと
上司になんだこれ？書き直せとなって、クレーム来るかもしれないけど
（でも、納品した書類、客先担当者はまともに見ないってばさ（笑））
関数仕様書は、
~~~~~~~~~~~~~~
簡単な呼び出しモジュール（モジュールのテストを兼ねた）
と
簡単な機能説明で十分だと三流プログラマーのＫｅｎ３は思います。

Sub Test_Main()

    Dim nNO As Integer

    nNO = selectCODE("A001")  '動作番号1,2,3を返す
    Select Case nNO
        Case 1:  '在庫確認処理
            MsgBox "在庫確認処理を呼ぶ"
        Case 2:  '納品待ち
            MsgBox "納品待ち"
        Case 3:  '出荷処理
            MsgBox "出荷処理"
        Case Else
            MsgBox "オイ、そんなリターン値ないよ・・"
    End Select

End Sub

なんて、テストモジュールを書いといて、
selectCODEを作成する担当者に、
文字列でコードを受け取り、A.mdbからデータを受け取り、在庫テーブルと照合、
さらに、入庫予定がONなら・・・を返す
・
・
と、書けば、作るほうも作ってもらうほうも楽なのでは？

おまけでつけた、テストモジュールが、
メインモジュール作りにもなったりして、
矛盾点の確認にもなるし、関数仕様書／関数作成依頼書作るときは、
一緒にテストモジュールも付けてみては？

/*
 * ４．じゃ、一人作業の時は、仕様書は頭の中にありますでいいの？かよ？
*/

仕様書は、他のメンバーと意思の疎通をスムーズにするため必要、
でも、しょせん仕様書なんて納品時にページ稼ぎ、仕様書は見ない、
ソースを見たほうが正確だぁ〜
なんて言ってると、
一人作業の時は、仕様書は頭の中にありますでいいよ
って聞こえるんだけど、そのあたりは？

う〜ん、、、仕様書は私の頭の中にありますかぁ・・・
ほんとに一人作業なら、それもアリかもしれないけど、
さっき、チラっと書いたけど、未来の自分へのラブレターとして、
書いておくと、下位モジュールのテスト時楽だし、
納品用の書式に書く必要は無いけど、メモ書き程度は、書いたほうがいいよ。

私が変わり者だからかもしれないけど、
未来の自分に依頼を出すって感じで、まとめると、面白いかもね。

自分自身に仕様書を書いてオーダーする
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
なかなか、イメージ沸きにくいけど、
こんな仕様作ったバカは誰だよ・・・あっ、自分だった（笑）
私みたいに、たまには、右脳と左脳でケンカしてね。

※メルマガの作者とサンプルプログラム作成者って違うんですか？
　と質問受けたことあったけど、同じ人がどちらも書いてます（笑）
　気分によって、文体やサンプルに違いがあるんだけどね・・・
  アシスタントを雇うぐらい儲けたいけど、そんな夢見ちゃねぇ・・・

/*
 * ５．終わりの挨拶
*/

今回は、
関数仕様書の書き方は、
・ＶＢＡのヘルプと同じ書式でいいんじゃないの？
・テストルーチンを付けて渡すと、理解がハヤマルよ
・自分自身に仕様書を書いてオーダーする

何か読者の心に残れば、うれしいです。
＊私の独り言をうまく消化してくださいね。

いつも失敗？のＫｅｎ３でした。
~~~~~~~(↑オイオイ)

ページフッター

ここまで、読んでいただきどうもです。ここから下は、三流君のホームページの紹介・案内です
目的の情報が見つかったか？少々心配しつつ、、、

リンクや広告など

項目別に本音？それとも建て前？的な記事をまとめました。

Blogとリンク:[三流君の作業日記]/ [愚痴(Bookmark)]/ [広告Blog(Bookmark)]