ソースコードのドキュメント
開発者のみんな、こんにちは。ようやく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、そのアカウントに保存されたアドレスが使用済みになったら新しいビットコインアドレスに変更する方法などだ。以前フォーラムでサンプルコードの断片を投稿した。（getreceivedbylabelまたは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