ソースコードのドキュメント
他の開発者の皆さん、こんにちは。ようやくUbuntuマシン上でビルド環境を構築でき、ソースコードを少し読んでみました。今のところ気に入っています。プログラムは標準テンプレートライブラリを活用して煩雑なデータ構造コードを避けており、クラス構造もpublic/privateアクセスをうまく使ってモジュール性を促進しているようです。
しかし、本当に不足していると思われるのは、.hファイルと.cppファイル間の適切な構成、そして関数のドキュメントです。Doxygenドキュメントシステムを使って、関数のドキュメントを書き始めたいと思います。私が開発リーダーを務めているゲームOpenDungeonsでもこれを使用しており、大変役立っています。
Doxygenに馴染みのない方のために説明すると、Doxygenはソースファイルを読み取り、自動的に収集する情報（関数のパラメータ、クラスの構成と継承など）と、自分で追加する情報（関数の説明、変数の用途など）を抽出します。すべてのコードを解析した後、相互リンクが充実し閲覧しやすいHTMLファイル群を含むディレクトリを生成します。また、各関数からどのサブ関数が呼ばれるかを示すコールグラフの自動生成も設定できます（依存関係やバグの追跡に役立ちます）。
全体として、Doxygenは優れたシステムであり、セットアップして関数のドキュメント（少なくとも私が理解できるもの）を書き始め、パッチを提供してSVNにアップロードできるようにしたいと考えています。ただし、他の開発者が反対するのであればやりたくないので、始める前にここに投稿しました。やってほしいかどうか教えてください。
編集：既存システムのドキュメントがどのようなものか見たい方のために、OGRE 3Dレンダリングシステムのドキュメントへのリンクを掲載します。ドキュメントの雰囲気をつかむには、上部の「Classes」リンクをクリックして、いくつかのクラスのページを見るのが最良です。
-Buck
Quote from: lachesis on July 15, 2010, 11:57:19 PM
いいと思うが、いつものように、最終決定はプロジェクトリーダーのサトシ次第だ。
これに反対する人がいるとは思わなかった。サトシからOKを正式にもらえるといいのだが。おそらく今夜から作業を始める（米国時間の今夜）。また、パッチの送り方を質問する別のスレッドを見た。回答はサトシにメールすべきとのことだったが、これがまだ推奨される方法だろうか？
-Buck
外部APIのライブラリではそれが好きだが、コードから察せるように、内部関数に対しては好みではない。各関数の大きな義務的コメントヘッダーはコードを間延びさせ、コメントヘッダーが関数より大きくなるような小さな関数の作成をためらわせる。メンテナンスの手間もかかり、関数の変更にはコメントヘッダーの重複した変更が必要になる。コードをコンパクトに保ち、画面上でより多くのコードを一度に見られるようにしたいのだ。
今の段階でそれらを追加しても、関数を見れば明らかなことしか書かれないだろう。
外部APIはrpc.cppにあり、使用方法のドキュメントはヘルプ文字列に記載されている。
せっかくの提案に水を差してすまない。
問題ない。だからこそドキュメントを書き始める前に確認した。それでもドキュメント化したいし、受け入れられるシステムを見つけられるかもしれない。一つの方法は、自分のコードに対してDoxygenを実行し、説明などを追加せずに自動生成されたドキュメントだけを使うことだ。これならプロジェクトに影響はないが、ドキュメントの有用性は制限される。
2つ目の、おそらくより魅力的な方法は、Doxygenがドキュメントしているソースコードと同じファイルに追加ドキュメントを含める必要がないという事実を利用することだ。関数名へのリンクを持つドキュメントブロックを含む単一のファイルを追加できる。Doxygenはこれをソースから収集した自動生成情報と組み合わせてドキュメントを生成する。
最後に、Doxygenを使うかどうかに関係なく、プログラムのコマンドラインオプションを文書化する「manページ」を書きたい。コマンドラインはコードのどこで処理されているだろうか？ main.cppを見たが見つからなかった（実際、“main”関数すら見つからなかった）。
-Buck
init.cppにある。
wxWidgetsアプリなので、main()関数はない。もうすぐあるかもしれない。bitcoindをwxBaseなしでビルドできるようにするのがかなり近いところまで来ている。（init.cppに入る予定だ）
ファイル名を「main.cpp」にしてしまい申し訳ない。別の選択肢としては「core.cpp」がありえた。今さら変更するには遅すぎる。個人的にはまだmain.cppが好みだ。
JSON-RPC関数の推奨使用方法を示すサンプルコード、例えば典型的なオンラインショップのウェブサイトにおける基本的なアカウントシステムの実装が非常に必要だ。ユーザー名をラベルとして使用するgetreceivedbylabel、そのアカウントに保存されたアドレスが使用済みになったら新しいビットコインアドレスに変更する方法などだ。以前フォーラムでサンプルコードの断片を投稿した。（getreceivedbylabalまたはgetnewaddressで検索してほしい）サンプルコードは、入金と支払い送信ができるプレーンなバニラ銀行サイトにできるだろう。
自分に返信し続けて申し訳ないが、見つけた小さな断片を投稿していく。現在-dropmessagestestコマンドラインスイッチのドキュメントを作成中で、コードに追加したい小さな改善を見つけた。現在、このスイッチの結果としてメッセージがドロップされると、メッセージがドロップされたことを示すデバッグメッセージがログに出力される。ドロップされたメッセージの内容もログに出力すると便利だろう。そうすれば、ドロップされたメッセージの1つが本当にBitcoinを壊した場合、どのメッセージが問題を引き起こしたかわかる。また、後でその問題を修正したことを確認するために、最初に壊したメッセージのようなものをブロックする受信ネットワークストリームのフィルターを追加して問題を再現できる。
良いアイデアだと思えば、自分で追加することもできるだろう。
-Buck
意図的にドキュメント化していないすべてのコマンドをドキュメント化するつもりだとは思わなかった。それらはサポート対象外であり、ユーザーが使用することを想定していない。
ユーザー向けのすべてのコマンドは -? ヘルプに一覧表示されている。
これらは本来、一般ユーザー向けのものではないのだろうと思った。しかし、少なくとも今のところは文書化しておくのが有用だと思う。プログラムが有効な入力として受け付けるなら、文書化すべきだ。manページのコマンドに実験的である旨の注意書きを追加するか、単に削除するかだ。私の意見では、実験的とラベル付けして変更される可能性があることを知らせつつ、必要なら使えるようにする方が理にかなっている。makefileの各コマンドの先頭に以下を追加するだけだ：
\fBUnsupported - Behaviour may change in future versions\fR
\fBで太字をオンにし、\fRで通常に戻す。こうすれば開発段階でプログラムを最大限に活用できる。ドキュメントが多すぎて困ることはない、特にオープンソースプロジェクトでは。コードが見えるのだから、どのみちこれらの呼び出しを見つけて使うだろう。文書化して変更可能性が明示されていれば、使うかどうかについて情報に基づいた判断ができる。
例えば、まさに今、IRCで誰かが-printblockコマンドを使ってブロックチェーンの統計情報を生成し、プログラムの動作をよりよく理解しようとしている（実際の環境でどう動くかという意味で）。このコマンドの出力は将来変わるかもしれないので、その上に複雑なフレームワークを構築すべきではないが、ちょっとしたハックが必要な時にその存在を知っているのは良いことだ。また、プログラムがオープンソースなので、あるコマンドラインスイッチに依存するようになれば、それをメンテナンスできる。一時的なデバッグツールだと思っていたものが、結局最も広く使われるスイッチの1つになるかもしれない。
-Buck