●見るためのマニュアル

01552/01552 VFF15672  T's-Neko         RE:class manualかくあるべし？(笑)
( 6)   98/08/02 11:23  01548へのコメント

  戯音匠者 さん、こんばんは。T's-Neko です。(^o^)o

（普通のマニュアルについて）
普通のマニュアルかわかりませんが、会社では仕様書レベルの文章が
あっても、たとえば、この構造体は何だとかいう、プログラムレベルの
文章は無いことが多いです。プログラマはソースコードから
理解できるものだ、とは思ってないでしょうけど。
（後先を考えてるほどひまじゃないから？）

ただ、主な関数については、機能の解説、引数の解説、
（それ以外の）補足、（文章ではわかりにくい場合）例が
書かれた文章があります。
クラスの使える言語の仕事をしないので、クラスの解説のある
普通のマニュアルはわかりません。

ただ、戯音匠者 さんの望む抽象クラスについては、
内部的な扱いをすることが多いと思うので、
クラスの使える言語の仕事をしても、そういった文章が
残る可能性は少ないと思います。

>実例じゃなくて皆さん（ooについて何らかの考えを持つ人）の
>考え方でもいいですから、きかせてください。

（理想のマニュアルについて）
僕のホームページを見られたことと思いますが、
ソースコードにマニュアルを埋め込んでいます。
これは、マニュアル作成の工数を減らすためと、
ソースとマニュアルの一貫性を維持するためですが、
コメントでは十分な情報が書かれないので、
理想のマニュアルから離れています。

それでも、プログラム作成においては理想のものに
かなり近いものだと感じています。
中には１年たつモジュールもありますが（まだ１年だけど）、
まったくわけのわからないモジュールがありませんから、
必要最低限の情報は満たしています。
あれ以上、理想のマニュアルに近づけると、
マニュアル作成に使う工数が増え、逆に全体の工数が
増えてしまいます。

ところで、理想のマニュアルを知るためには、
マニュアルを見る環境が整うような
環境を作ることが非常に重要なことだと思います。
呑舟さんが、smalltalk にツールがあることを
おっしゃっていますが、smalltalk じゃなくても可能です。
その答えの１つとして、Knowledge Take! というツールを
作りました。これは、ライブラリの情報を指先で取り出せるために
作ったものですが、ネットサーフィンならぬソースサーフィン
しているうちに、何の情報が不足しているわかるようになりました。
マニュアルは見る人のための情報ですから、
作る人がすぐに見る人の立場になることができる環境が
大事だと思います。見る人になるには、サンプルプログラムを
作るのが手っ取り早いですけど、実際にマニュアルを見るには、
ソースサーフィンなど敷居の低いメディアが有用だと思います。

そして、マニュアル作成を定型作業にするために、コメントの
フォーマットを決めました。

関数については、前に述べたように、機能の解説、引数の解説、
（それ以外の）補足、（文章ではわかりにくい場合）例を
書きます。

/*********************************************************
*  <<< [関数名] 概要（〜する）>>>
*【機能】
*・少し詳細な機能の説明を書く（概要では理解できない場合のみ）
*【引数】
*  ・引数と返り値について、型、変数名、説明を書く
*  ・ただし、説明は、制限や入出力・役割よりも、「何か」を書く
*  ・１つの引数について複数行書かない
*【補足】
*・ユーザにとって知ってもらいたいこと
*・引数の詳細な説明（必要な場合のみ）
*・「状態」が変化する変数について
*・通常期待される機能に「制限」が付く場合の説明
*【内部補足】
*・関数の内部を理解するのに知ってもらいたい事を書く
*【例】
*・プログラム記述例
*・入出力の値の例
**********************************************************/

クラスについては、機能に代わり役割、引数の代わりにメンバ
（属性と操作）を書くようにしています。このクラスは何(What)か、
という情報より、このクラスは何のため(Why)かという情報を
書きます。

/*********************************************************
*  <<< [クラス名] 概要（体言止め） >>>
*【役割】
*・概要では理解できない場合のみ、以下について書く
*  ・「機能」クラスの場合、少し詳細に機能の役割を書く
*  ・「原子」クラスの場合、少し詳細に何を表現したものかを書く
*【補足】
*・ユーザにとって知ってもらいたいこと
*・メンバ変数の詳細な説明（必要な場合のみ）
*・「状態」が変化する変数について
*・通常期待される機能に「制限」が付く場合の説明
*【内部補足】
*・クラスの内部を理解するのに知ってもらいたい事を書く
*【例】
*・プログラム記述例
*・入出力の値の例
**********************************************************/

具体的には、ホームページに掲載されているコンポーネント・
ライブラリを参考にしてください。

--- Neko.