c++boost.gif (8819 bytes) Home Libraries People FAQ More

Boostライブラリの要求事項とガイドライン
(Boost Library Requirements and Guidelines)

導入
要求事項
ライセンスに関する要求事項
移植性に関する要求事項
所有権
ガイドライン
デザインとプログラミング
ディレクトリ構造とファイル名
命名の一貫性
ドキュメント
論拠
Exception-specificationの論拠
命名ルールの論拠
ソースコードのフォントの論拠
タブの論拠
ECMAScript/JavaScriptの論拠
論拠の論拠
謝辞の論拠

導入 (Introduction)

このページはBoostに投稿されるライブラリの内容に関する要求事項とガイドラインを記したものである。

投稿のプロセスに関する説明は Boost Library Submission Processを見よ。

要求事項 (Requirements)

提案されたライブラリを却下するのに費やされる無駄な時間と徒労感を避けるため、投稿されるライブラリは以下の要求事項を満たす必要がある。

作者は投稿する前にメーリングリストを読む必要はない。しかしながら、付け加えておくと、 「たったいまメーリングリストを読み始めたところなのですが・・・」というような 文言で始まる投稿はうまくゆくとは思えないし、戸惑いをもって受け止められるだろう。

ライセンスに関する要求事項 (License Requirements)

移植性に関する要求事項 (Portability Requirements)

移植性を検証する絶対的な方法は存在しないので、boostへ投稿される多くのライブラリは、 二つのコンパイラ(多くの場合OSも異なる)でコンパイルし実行することで実際的な移植性を実演している。 そうしなければ、portが本当に実際上うまくいくのかレビュー担当者が疑問を持つようになる。

所有権 (Ownership)

投稿しようとしているライブラリは本当にあなたが所有権をもっているものですか? "How to Copyright Software" by MJ Salone, Nolo Press, 1990は以下のように書いている。

自分の時間を割いてやった仕事でも、それが会社で雇い主のためにやっているプログラミングと似通っているなら 法律上、厄介な問題を抱えることになるだろう。このような状況の時は、前もって雇い主から明文化されたリリースを得ておくのがよい。

投稿する全ての重要なファイルにcopyrightをつけよう。Boostは明示的なcopyright情報がないものは受け入れない。

ガイドライン (Guidelines)

ライブラリの投稿にあたって内容を準備するためのチェックリストとしてこのガイドラインをご利用ください。 全てのガイドラインが全てのライブラリに当てはまるわけではないが、従うおうとする努力に見合う内容だとおもう。

デザインとプログラミング (Design and Programming)

ディレクトリ構造とファイル名 (Directory Structure and Filename)

Boostの標準的なサブディレクトリ名

サブディレクトリ 内容 必要なとき
build ライブラリのビルド用ファイル(例えばJamfile) もしなにかbuildファイルが必要なら
doc ドキュメント(HTML)ファイル もし複数のドキュメントファイルがあるなら
example サンプルプログラムのファイル もし複数のサンプルプログラムがあるなら
src ライブラリをコンパイルしビルドするのに必要なソースファイル もしなにかソースファイルがあるなら
test 退行テストその他テストプログラム、またはスクリプト。 もし複数のテストファイルがあるなら

リダイレクト

最上位のディレクトリは常にindex.html(またはindex.htm)というファイルを含まなければならない。 著者らがこれらを要求した。これによってURLをhttp://www.boost.org/libs/lib-name の形で記してもURLが無効とならないと保証できる。 簡易的なURLの表記でも必ずドキュメントに到達できるということを利用してBoostの内部ツールをシンプルにすることができた。

もしドキュメントがdocサブディレクトリにあるなら、最上位ディレクトリにあるindex.htmlは docサブディレクトリへの自動的なリダイレクトのみを行う。

<html>
<head>
<meta http-equiv="refresh" content="0; URL=doc/index.html">
</head>
<body>
Automatic redirection failed, please go to
<a href="doc/index.html">doc/index.html</a>
</body>
</html>

命名の一貫性 (Naming consistency)

ライブラリの開発者は、Boostで経験を積むにしたがって 以下のような一貫した命名のアプローチがとても役に立つと考えるようになった。 サブディレクトリや名前空間を持つ大きなライブラリについては特に役に立つ。

どのようになっているのか説明するとしよう。 ライブラリは中身が分かるような名前を与えられる。暗号じみた省略は受け入れられない。 C++標準ライブラリでの作法に従って、名前は普通、複数形ではなく単数形である。 例えば、ファイルシステムを扱うライブラリなら、"filesystem"と命名され、"filesystems","fs","nicecode"という名前にはならないだろう。

ドキュメント (Documentation)

一番シンプルなライブラリでさえ、いくらかのドキュメントが必要だ。但し、量は必要に応じて変わってくるだろう。 ドキュメントは、読者がC++の基礎的な知識があることを前提とするが、エクスパートであることは前提としない。

ドキュメントのフォーマットはHTMLであり、高度なブラウザやサーバサイドの拡張を必要としてはならない。 スタイルシートは受け入れられる。ECMAScript/JavaScriptは受け入れられない。 ドキュメントの入り口は常に、index.html または index.htmでなければならない。 Redirectionを見よ。

ドキュメントの書き方は一つの正しい方法があるわけではない。 HTMLドキュメントは従来の印刷物とはかなり異なった方法で構成される。 Task-Orientedなスタイルはreference-orientedなスタイルとは異なる。 結局、こういう疑問がでてくる。 謎に包まれた「平均的な」C++プログラマとやらがうまくライブラリを使いこなすのに ドキュメントは十分だろうか?

ドキュメントのための適切な内容は以下のようなものだ。

もしドキュメントの書き方についてもっと知りたいなら Writing Documentation for Boostを見よ

論拠 (Rationale)

要求事項とガイドラインのいくつかに関する論拠(rationale)


Exception-specificationの論拠 (Exception-specification Rationale)

Exception specifications [ISO 15.4] は、投げられるかもしれない例外を示したり、あるいはプログラマがパフォーマンスを向上させる たいと願って、時々使われる。しかし以下のようなスマートポインタからのメンバを考えてみてほしい。

    T& operator*() const throw()  { return *ptr; }

この関数は他の関数を呼ばない。単にポインタのような基本型のデータを操作しているだけである。したがって 実行時には決して exception-specification のふるまいが引き起こされない。 この関数は完全にコンパイラに曝されていて、実際この関数はインラインとして宣言されている。 従って性能の良いコンパイラならすぐにこの関数が例外を投げることはないと見抜いて、exception-specificationのないときと同じ 最適化を行うことができるだろう。しかし、「駄目な」コンパイラでは悲惨なことになってしまう。

例えば、あるコンパイラはexception-specificationがあるとインライン化を中止する。 またあるコンパイラはtry/catchブロックを追加する。これでは実際のアプリケーションで 利用できないようなパフォーマンスの劣化につながる。

最初は魅力的に見えても、exception-specificationはとても注意して理解する必要のある結果を招きがちだ。 最大の問題はプログラマは自分に好ましいような結果を期待して利用するが、実際はなるようにしかならない、ということだ。

インラインでない関数なら、"どんな例外も投げない"exception-specification でも いくつかのコンパイラでいくらかの利益が得られるかもしれない。


命名ルールに関する論拠 (Naming conventions rationale)

C++標準化委員会のライブラリワーキンググループは この問題について詳細にわたるまで、長い期間議論した。 議論は初期のboostの投稿でも再度繰り返された。 以下は短いまとめである。


ソースコードのフォントの論拠 (Source code font rationale)

Dave Abrahamsのコメント:
ソースコードの最も重要な目的は(私は敢えて一番の目的だというが)コミュニケーションである。 すなわち意図のドキュメント化だ。これはboostにとって二重に重要だとおもう。 固定幅フォントの使用によって、(ダイアグラムのような)より多くの方法で ソースコードによるコミュニケーションが可能となる。 スペースと固定幅フォントによるコードは、可変長フォントで見てもそこそこうまく見える。 私の知る限り可変長のフォントをサポートするエディタは固定長フォントもサポートしている。 逆は真でない。


タブの論拠 (Tabs rationale)

タブは禁止される。これは主義主張の上での好き嫌いとは関係ない。 Boostのような複数の開発環境を利用するプロジェクトで実際的な問題があるためである。 Boostメーリングリストのarchivesをみよ。 タブを使うプログラマとスペースを使うプログラマが一つのファイルをメンテナンスする場合、 一貫したタブのポリシーを強制するのが難しいのに比べて「タブ無し」というルールは簡単だ。 結局、Boostのファイル全てを、タブかスペースで統一すべきだということになった。そしてスペースが選ばれた。


ECMAScript/JavaScriptの論拠 (ECMAScript/JavaScript Rationale)

1.29.0のリリース前に二つのBoostライブラリがECMAScript/JavaScriptのドキュメントを加えた。 議論は紛糾した。Boostメーリングリストのarchives そして開発者は、ECMAScript/JavaScriptを削除するように、ということになった。 禁止の理由には以下のようなものが含まれた。


Rationaleの論拠 (Rationale rationale)

Rationale という言葉は "The fundamental reasons for something; basis" と定義される。(the American Heritage Dictionary)

Beman Dawesのコメント
デザインの決定と同時にRationale(論拠)を決定できないことはソフトウエアプロジェクトにおける大きな欠点となる。 緻密なRationaleが存在しないと、終わりなき話題が何度も議題となり、 メンテナがそのコードの目的と方法を理解できないまま変更を行ってバグを生み出し、ソフトウエアの寿命を短くすることになる。

決定を下したときにRationaleを提供するのはたやすい。しかし少しでも後になると回復するのは難しい。


謝辞の論拠(acknowledgment rationale)

ライブラリが成熟するに従って、他のboostメンバからの指摘によって改善されてゆくのはよくあることだ。 貢献者を同定し、これらの貢献に対して謝意を示すのはboost.orgの文化の一部である。 大きな貢献はドキュメントに記され、小さな訂正はコード自体にコメントとして書き込まれる。


Revised 26 February, 2003

Japanese Translation Copyright (©) 2003 Satoshi Fujimoto
オリジナルの、及びこの著作権表示が全ての複製の中に現れる限り、この文書の複製、利用、変更、販売そして配布を認める。 このドキュメントは「あるがまま」に提供されており、いかなる明示的、暗黙的保証も行わない。また、いかなる目的に対しても、 その利用が適していることを関知しない。

Japanese Translation Last Revised: 4/29/2003

原文 : Boost 1.30.0 Boost Library Requirements and Guidelines