6. プログラムの文書化

6.1 GNUマニュアル

GNUシステムの一部を文書にする好ましい方法はTexinfo整形言語 でマニュアルを書くことだ。Texinfoのマニュアルを、ハードコピーか、 infoやEmacsのInfoサブシステム(C-h i)を使って利用できるオン ラインのバージョンで見なさい。

プログラマはしばしば、彼らが知っている実装の構造に従う文書を構成するのが 最も自然だと感じる。しかしこの構造はそのプログラムの使い方を説明するには 必ずしも良いとは言えない。それはユーザには関係がなく、ユーザを混乱させる かもしれない。

段落の文から別々のマニュアルに論題を分類することまで、あらゆる水準で、文 書を構成する正しい方法は、それを読むときにユーザが心に抱くであろう概念や 疑問に従う。ときどきこの考えの構造は文書化されるソフトウェアの実装の構造 と一致する。---でもしばしばそれらは異なる。しばしば良い文書を執筆するた めに学ぶ一番重要な部分は、実装のように文書を構成していて、もっと良い別の 構成について考えるときに気付くことを学ぶことだ。

例えば、GNUシステムのそれぞれのプログラムはおそらく一つのマニュアルに記 述されるべきだ。しかしこれはそれぞれのプログラムがそれ自身のマニュアルに 文書化されるべきであることを意味していない。このことはユーザが理解するの を助ける構造よりもむしろ、その実装の構造に従っているだろう。

代わりに、それぞれのマニュアルは密接な論題を包含するべきだ。例え ば、diffのマニュアルとdiff3のマニュアルの代わりに、 cmpだけでなく、これらのプログラム両方も包含する、"ファイルの比較" のマニュアルが一つある。それらのプログラムを一緒に文書にすることで、全体 の主題をよりすっきりさせることができる。

プログラムを論じるマニュアルはそのプログラムのコマンドライン・オプション 全てとそのコマンド全てを記述すべきだ。それはそれらの使用例を与えるべきだ。 しかしマニュアルを機能の列挙として構成してはならない。代わりに、副題によっ て、論理的に構成しなさい。プログラムが行う仕事について考えるときにユーザ が尋ねるであろう質問を提出しなさい。

概して、GNUマニュアルは指導書と参考書の両方に役に立つべきだ。それはInfo によりそれぞれの論題に対する便利な手段のために、そして(付録は別として)通読 するために作り上げられるべきだ。GNUマニュアルは始めから通して読む初心者 への良い紹介を行うべきで、ハッカーが欲しがる詳細のすべてを与えるべきでも ある。

そのことは最初に思われるほど難しくない。それぞれの章をその論題の論理的な 分類として整理しなさい。しかしその節を整頓して、それらのテキストを執筆し なさい。その章を通読することが意味を為すように。その著書を章に構成すると きや、節を段落に構成するとき、同様にしなさい。その標語は、それぞれ の地点で、先行するテキストによって上げられた最も基本的で最も重要な話題を 提出しなさい、だ。

必要なら、マニュアルの最初に、純粋に指導的で、主題の基礎を包含する、余分 な章を入れなさい。これらは初心者がマニュアルの残りを理解するための枠組み を提供する。Bisonのマニュアルはこれの使い方の良い例を提供する。

GNUの文書を書き方の手本としてUnixのmanページを使ってはいけない。それらの ほとんどは簡潔で、構成が悪く、根底にある概念について不適切な説明を与えて いる。(もちろん例外はある。) またUnixのmanページはGNUマニュアルで使用す るものとは異なる、特有の構成を使用する。

Unixの文書で使われる"pathname"という用語を使わないでください。代わりに "file name"(二語)を使いなさい。"path"という用語は検索パスに対しての み使用し、それはファイル名のリストだ。

コンピュータ・プログラムへの間違った入力を表すのに、"illegal"という用 語を使わないでください。このためには"invalid"を使い、"illegal"という 用語は違法のために確保してください。

6.2 マニュアルの構造の詳細

マニュアルの表紙は、そのマニュアルで記述されるプログラムやパッケージのバー ジョンを述べるべきだ。マニュアルの一番上の節もまたこの情報を含むべきだ。 もしマニュアルがプログラムより頻繁に、あるいは、無関係に変更されているな ら、それらの場所の両方で、そのマニュアルのバージョン・ナンバーを記述しな さい。

そのマニュアルで記述されるそれぞれのプログラムは、`program Invocation'とか`Invoking program'と名付けられた節を持つべきだ。 この節は(もしあれば、その副節と共に)そのプログラムのコマンドラインの引数 とそれの走らせ方(人々がmanページで探し求める情報の類い)を記すべきだ。そ のプログラムが使う、すべてのオプションと引数のテンプレートを含む `@example'で始めなさい。

あるいは、項目の名前が上の様式の一つに合う表に項目を書きなさい。これ は、その節の本当の名前とは関係なしに、この目的のための節として、項目が指 し示す節を識別する(5)。

プログラム名を指定し、そのマニュアルのこれの部分だけを素早く読むための自 動的な機能があるだろう。

もし一つのマニュアルがいくつかのプログラムを記述するなら、それぞれのプロ グラムを記述する節を持つべきだ。

6.3 NEWSファイル

マニュアルに加えて、パッケージは言及するに値するユーザに見える変更の 一覧を含む`NEWS'と名付けられたファイルを持つべきだ。新しいリリー ス毎に、そのファイルの前に項目を加え、それらが属するバージョンを同定しな さい。古い項目を捨てないように。新しい項目の後へ、そのファイルの中に残し ておきなさい。こうして、以前のどのバージョンからアップグレードするユーザ でも何が新しいのかを見ることができる。

もし`NEWS'ファイルが非常に長くなれば、古い項目をいくらか `ONEWS'という名前のファイルに移し、ユーザがそのファイルを参照するた めに最後に覚え書きを書いておきなさい。

6.4 変更履歴

変更履歴にプログラムのソースファイルに行われた変更を全て記述し続けなさい。 これの目的は将来バグを発見する人々がそのバグを入れた変更が分かるようにす ることだ。しばしば新しいバグは最近何が変わったのかを見ることで発見され得 る。さらに重要なことに、変更履歴は矛盾する概念がいかに起きそれらが誰 に起因するのかということについての履歴を与えてくれるので、プログラムの 異なる部分間での概念的な矛盾を失くすことに役立つことができるのだ。

6.4.1 変更履歴の概念

変更履歴を、もっと前のバージョンが現在のバージョンとどう違うかを説明する、 概念な"復元一覧表"として考えることができる。人々は現在のバージョンを見 ることができる。彼らは何がその中にあるのかを言うのに変更履歴を必要としな い。変更履歴から欲しいものはもっと前のバージョンがどう違ったのかに関する、 すっきりした説明だ。

変更履歴ファイルは通常`ChangeLog'と呼ばれ、ディレクトリ全体を包含す る。それぞれのディレクトリはそれ自身の変更履歴を持って良いし、あるディレ クトリはその親ディレクトリの変更履歴を使って良い。---それはあなたに任さ れる。

他のやり方は変更履歴をRCSやCVSのようなバージョン管理システムで記録するこ とだ。これは自動的に`ChangeLog'ファイルに変換される。

変更の目的全部やそれらが一緒にどう働くのかを記述する必要性はない。もし変 更が説明を必要とすると考えるなら、おそらくその通りだ。それを説明してくだ さい。---しかしコードのコメントに説明を入れてください。そこは人々がその コードを見るときはいつでも見るところだろう。例えば、関数を加えるとき、 "New function"は変更履歴には十分だ。なぜなら、それが何をするのか説明す るために、関数定義の前にコメントがあるはずだからだ。

しかしながら、ときどき変更の組の全体の目的を記述する一行を書くのが有用だ。

`ChangeLog'に項目を加える一番簡単な方法はEmacsのコマンド、M-x add-change-log-entryを使うことだ。項目はアスタリスク、変更されたファイ ルの名前、そして変更された関数、変数、それ以外のものの名前を丸括弧の中に 含むべきだ。その後にコロンを付ける。そしてその関数や変数に行った変更を記 述しなさい。

6.4.2 変更履歴の形式

ここに変更履歴の項目の例をいくつか挙げる。

* register.el (insert-register): Return nil.
(jump-to-register): Likewise.

* sort.el (sort-subr): Return nil.

* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
Restart the tex shell if process is gone or stopped.
(tex-shell-running): New function.

* expr.c (store_one_arg): Round size up for move_block_to_reg.
(expand_call): Round up when emitting USE insns.
* stmt.c (assign_parms): Round size up for move_block_from_reg.

変更された関数や変数を略さずに名前を付けることが重要だ。関数や変数の名前 を略していけない。そして、それらをくっ付けてはいけない。その後の管理者は しばしばある関数に属する変更履歴の項目を全部見付けるのに、関数名で検索す るだろう。もしその名前を略していると、彼らは検索するときそれを見付けられ ないだろう。

例えば、ある人々は`* register.el ({insert,jump-to}-register)'と書 くことで、関数名の集まりを略する傾向がある。これは良くない考えだ。 jump-to-registerやinsert-registerの検索はその項目を見付け ないだろうから。

無関係な変更履歴の項目を空行で分けなさい。二つの項目が一緒に働き、同じ変 更部分を表しているとき、それらの間に空行を入れてはいけない。そして、続い ている項目が同じファイルにあるとき、そのファイル名とアスタリスクを省いて 良い。

6.4.3 単純な変更

ある単純な類いの変更は変更履歴にやたら詳細に記す必要はない。

単純なやり方で関数の呼び出し順序を変更し、その関数の呼び出し元を全て 変更するとき、変更した呼び出し元全てに個々の項目を作る必要はない。単に 呼ばれる関数の項目に"All callers changed"と書きなさい。

* keyboard.c (Fcommand_execute): New arg SPECIAL.
All callers changed.

コメントや解説の文字列だけを変更するとき、関数に言及せずに、そのファイル の項目を書けば十分だ。単なる"Doc fixes"だけで変更履歴には十分だ。

解説ファイルのための変更履歴の項目は作る必要はない。これは解説は直すのが 困難であるバグに影響しないからだ。解説は正確に設計されたやり方で相互作用 するに違いない部分から成り立っているわけではない。誤りを正すために、間違っ た経過の履歴を知る必要はない。その解説が言っていることと、そのプログラム が実際に働く方法を比較すれば十分だ。

6.4.4 条件文の履歴

Cのプログラムはしばしばコンパイル時の#if条件文を含む。たくさんの 変更は条件文だ。ときどき条件文に全体的に含まれている新しい定義を加える。 変更履歴にその変更が適用されるのがどれか条件を示すことは非常に役に立つ。

条件付きの変更を示す我々の慣習は条件の名前の周りに角括弧を使うことだ。

ここで、条件付きだが、それに付随する関数や実体の名前を持たない変更を記述 する、簡単な例を挙げる。

* xterm.c [SOLARIS2]: Include string.h.

ここで全部条件付きである新しい定義を記述する項目を挙げる。 FRAME_WINDOW_Pというマクロに対するこの新しい定義は HAVE_X_WINDOWSが定義されているときだけ使われる。

* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.

ここに、全体として定義は無条件だが、変更自体は`#ifdef HAVE_LIBNCURSES'条件に含まれる、init_displayという関数内での変更 に対する項目を挙げる。

* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.

ここであるマクロが定義されないときだけ影響を持つ変更の項目を挙げる。

(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.

6.5 manページ

GNUプロジェクトでは、manページは副次的だ。あらゆるGNUプログラムがmanペー ジを持つことは必要でないか期待されていない。しかし一部は持っている。あな たのプログラムにmanページを含めるかどうかはあなたの選択である。

この決定をするとき、manページをサポートするにはそのプログラムが変更 される時毎に継続的な努力が必要であることを考えなさい。そのmanページに費 す時間はもっと有用な作業から奪われる時間なのだ。

ほとんど変更しない簡単なプログラムでは、manページの更新はちょっとした作 業かもしれない。そして、もし持っていれば、manページを含めない理由はほと んどない。

多量に変更する大きなプログラムでは、manページの更新は相当な重荷かもしれ ない。もしユーザがmanページを寄付すると申し出たら、この贈り物は受け取る のに高くつくと考えるかもしれない。同じ人がそれを維持する全責任を負うと合 意しなければ、そのmanページを拒否することがより良いかもしれない。---完全 にそれから手を洗えるように。もしこの有志が後にその作業をするのをやめたら、 自分でそれを取り上げなければならないと感じてはいけない。誰か他の人がその manページを更新すると合意するまで、配布物からそれを引込めるのがより良い かもしれない。

プログラムをほんの少ししか変更しないとき、manページは更新せずに役に立つ 状態に保たれるぐらい不一致は少ないと感じるかもしれない。そうなら、それを 維持しておらず、Texinfoマニュアルがもっと信頼できることを説明する目に付 く覚え書きをmanページの最初の方に書いておきなさい。その覚え書きはTexinfo 文書を呼び出す方法を表すべきだ。

6.6 他のマニュアルを読む

あなたが解説しているプログラムを記述する、自由でない書籍や解説ファイルが あるかもしれない。

単に新しい代数の教科書の著者が代数に関する他の本を読むことができるように、 これらの文書を参考文献として使って構わない。どのノンフィクションの書籍の 大部分も事実から出来ていて、この場合、あるプログラムがどう動くかについて の事実で、これらの事実はその主題で書いているすべての人にとって必ず同じで ある。しかし、すでにある自由でない解説文から、あなたの概要の構成、言葉遣 い、表や例を複製しないように気を付けなさい。自由な解説文から複製すること は構わないかもしれない。個々の場合についてFSFに確認してください。