ソースコードのドキュメント
他の開発者の皆さん、こんにちは。ようやく Ubuntu マシン上でビルド環境を構築でき、ソースコードを少し読んでみました。今のところ気に入っています。プログラムは標準テンプレートライブラリを活用して煩雑なデータ構造コードを避けており、クラス構造も public/private アクセスをうまく使ってモジュール性を促進しているようです。
しかし、本当に不足していると思われるのは、.h ファイルと.cpp ファイル間の適切な構成、そして関数のドキュメントです。Doxygen (http://www.doxygen.org) ドキュメントシステムを使って、関数のドキュメントを書き始めたいと思います。私が開発リーダーを務めているゲーム OpenDungeons (http://sourceforge.net/projects/opendungeons/) でもこれを使用しており、大変役立っています。
Doxygen に馴染みのない方のために説明すると、Doxygen はソースファイルを読み取り、自動的に収集する情報（関数のパラメーター、クラスの構成と継承など）と、自分で追加する情報（関数の説明、変数の用途など）を抽出します。すべてのコードを解析した後、相互リンクが充実し閲覧しやすい HTML ファイル群を含むディレクトリを生成します。また、各関数からどのサブ関数が呼ばれるかを示すコールグラフの自動生成も設定できます（依存関係やバグの追跡に役立ちます）。
全体として、Doxygen は優れたシステムであり、セットアップして関数のドキュメント（少なくとも私が理解できるもの）を書き始め、パッチを提供して SVN にアップロードできるようにしたいと考えています。ただし、他の開発者が反対するのであればやりたくないので、始める前にここに投稿しました。やってほしいかどうか教えてください。
編集：既存システムのドキュメントがどのようなものか見たい方のために、OGRE 3D レンダリングシステムのドキュメントへのリンク (http://www.ogre3d.org/docs/api/html/)を掲載します。ドキュメントの雰囲気をつかむには、上部の Classes リンクをクリックして、いくつかのクラスのページを見るのが最良です。
-Buck
いいと思うが、いつものように、最終決定はプロジェクトリーダーのサトシ次第だ。
これに反対する人がいるとは思わなかった。サトシから 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 で検索してほしい）サンプルコードは、入金と支払い送信ができるプレーンなバニラ銀行サイトにできるだろう。
JSON については何も知らないし、ウェブサイト設計の知識も非常に限られているので、ここでは役に立てない。だが C++についてはかなり広範な知識がある。コードベースに少しは手を入れられると思う。
現在、コマンドライン処理を標準的な unix/linux コマンドラインに近い挙動になるよう少し調整している（具体的には、ヘルプ表示用の -h を追加している）。現在のコードに基づいて man ページのテキストも書く予定だ。
書き上げたら man ページを wiki に載せるつもりだが、ソースコードのパッチはどこに提出すればいい？
編集：実際には man ページのマークアップ言語で man ページを書いているので、パッチにはこれも含める。wiki では意味不明に見えるだろうから。
-Buck
man ページの作業をまだ続けていて、かなり良い感じになってきた。だが、いくつか問題に出くわした。まず、-printtodebugger というコマンドラインオプションがある。-h を指定したときの「usage」情報に追加したし、man ページにも追加したが、コードを見ても何をするものなのか分からない――windows マシンでしか使われていない、ということ以外は。
第二に、OutputDebugStringF() 関数を調査する過程で、グローバル変数 fPrintToConsole を true に設定することでコンソールに出力できることが分かった。だが、その変数は false で初期化されていて、コード中のどこにも true に設定する箇所がなかった。そこで、この変数と fDebug の両方を true にする -printtoconsole を追加した。両方を設定すべきだと思うが、fDebug の方はそのままにしておくべきかどうか迷っている。コード内で設定しなければ、ユーザーはコマンドラインで -printtoconsole -debug と指定する必要がある。debug によって冗長性が増えるか減るかによって、これを望むかどうかは分かれる。だがコードをざっと grep した感じでは、今やっているように両方の変数を自動的に設定するのが正しいように見える。
-Buck
自分に返信し続けて申し訳ないが、見つけた小さな断片を投稿していく。現在 -dropmessagestest コマンドラインスイッチのドキュメントを作成中で、コードに追加したい小さな改善を見つけた。現在、このスイッチの結果としてメッセージがドロップされると、メッセージがドロップされたことを示すデバッグメッセージがログに出力される。ドロップされたメッセージの内容もログに出力すると便利だろう。そうすれば、ドロップされたメッセージの 1 つが本当に Bitcoin を壊した場合、どのメッセージが問題を引き起こしたかわかる。また、後でその問題を修正したことを確認するために、最初に壊したメッセージのようなものをブロックする受信ネットワークストリームのフィルターを追加して問題を再現できる。
良いアイデアだと思えば、自分で追加することもできるだろう。
-Buck
意図的にドキュメント化していないすべてのコマンドをドキュメント化するつもりだとは思わなかった。それらはサポート対象外であり、ユーザーが使用することを想定していない。
ユーザー向けのすべてのコマンドは -? ヘルプに一覧表示されている。
これらは本来、一般ユーザー向けのものではないのだろうと思った。しかし、少なくとも今のところは文書化しておくのが有用だと思う。プログラムが有効な入力として受け付けるなら、文書化すべきだ。man ページのコマンドに実験的である旨の注意書きを追加するか、単に削除するかだ。私の意見では、実験的とラベル付けして変更される可能性があることを知らせつつ、必要なら使えるようにする方が理にかなっている。makefile の各コマンドの先頭に以下を追加するだけだ：
\fBUnsupported - Behaviour may change in future versions\fR
\fB で太字をオンにし、\fR で通常に戻す。こうすれば開発段階でプログラムを最大限に活用できる。ドキュメントが多すぎて困ることはない、特にオープンソースプロジェクトでは。コードが見えるのだから、どのみちこれらの呼び出しを見つけて使うだろう。文書化して変更可能性が明示されていれば、使うかどうかについて情報に基づいた判断ができる。
例えば、まさに今、IRC で誰かが -printblock コマンドを使ってブロックチェーンの統計情報を生成し、プログラムの動作をよりよく理解しようとしている（実際の環境でどう動くかという意味で）。このコマンドの出力は将来変わるかもしれないので、その上に複雑なフレームワークを構築すべきではないが、ちょっとしたハックが必要な時にその存在を知っているのは良いことだ。また、プログラムがオープンソースなので、あるコマンドラインスイッチに依存するようになれば、それをメンテナンスできる。一時的なデバッグツールだと思っていたものが、結局最も広く使われるスイッチの 1 つになるかもしれない。
-Buck
つまり、あなたが書いているプログラム――人々に銀行業務や金融取引で使ってもらおうとしているプログラム――には、ソースコードを掘り下げた人だけが利用できる、ドキュメント化されていないインターフェースがあるべきだ、ということだな。しかも、それを見つけた後でさえ、それが意図的に存在するもの（ドキュメントから偶然抜け落ちただけ）なのか、いつでも削除・変更されうるものなのか、何の手がかりもないと。
-printblock コマンドは、クライアントの使用状況やスケーラビリティを研究するためのフレームワークを構築したい他の人にとって優れたインターフェースだ。-noirc コマンドは、ネットワーク上での自分の存在をどれだけ広めるかを制限したいプライバシー重視の人々に良いだろう。-dropmessagetest は、新しいブロックチェーンを持つ改変クライアントを構築してセキュリティ/スケーラビリティテスト用のテストネットワークを形成しようとする人にとって非常に便利だろう。あなたの定義によればこれらはすべて「開発者専用」だが、実際にはかなり有用だ。
俺はこの一週間、ビルド環境を整え、あなたのコードベースを学び、IRC で人々を助け、bitcoinmarket がより効果的に機能するためのツールを書くことに費やしてきた。それに加えて、他の人が同じことに時間を費やさなくて済むように、約 2日間かけて man ページを準備した。プログラムの背後にあるアイデアが素晴らしいものだと思っているからこそ、クライアントとプロトコルの両方を改善するつもりでこれをやってきた。だが正直なところ、オープンソース開発プロセスに対するあなたのアプローチを見ると、自分の時間は別のところに使った方が良いのではないかと思い始めている。
man ページの現在のバージョンを wiki に投稿した。誰か使いたい人がいればどうぞ。クライアント開発を続けるかどうかは分からないが、Dwdollar とマーケット関連の仕事は続けるだろう。
-Buck