|
Home | Libraries | People | FAQ | More |
導入
要求事項
ライセンスに関する要求事項
移植性に関する要求事項
所有権
ガイドライン
デザインとプログラミング
ディレクトリ構造とファイル名
命名の一貫性
ドキュメント
論拠
Exception-specificationの論拠
命名ルールの論拠
ソースコードのフォントの論拠
タブの論拠
ECMAScript/JavaScriptの論拠
論拠の論拠
謝辞の論拠
このページはBoostに投稿されるライブラリの内容に関する要求事項とガイドラインを記したものである。
投稿のプロセスに関する説明は Boost Library Submission Processを見よ。
提案されたライブラリを却下するのに費やされる無駄な時間と徒労感を避けるため、投稿されるライブラリは以下の要求事項を満たす必要がある。
ライセンスが下記のライセンスに関する要求事項 を満たすこと。GPLやLGPLのような制限付きのライセンスは受け入れられない。
copyrightの所有権が明確でなればならない。
ライブラリは、狭い問題領域に限定されず、一般に役立つものでなくてはならない。
ライブラリは、下記の移植性に関する要求事項 を満たす必要がある。
ライブラリは妥当だと思える範囲内で、下記のガイドラインを満たす必要がある。
作者は投稿する前にメーリングリストを読む必要はない。しかしながら、付け加えておくと、 「たったいまメーリングリストを読み始めたところなのですが・・・」というような 文言で始まる投稿はうまくゆくとは思えないし、戸惑いをもって受け止められるだろう。
(ライセンスは)読みやすく理解しやすいものでなければならない
用途(商用、非商用）を問わず、無償でそのソフトウエアのコピー、利用、修正を認めなければならない
Must grant permission without fee to copy, use and modify the software for any use (commercial and non-commercial).
ソフトウエアのソースコードの全てのコピーにライセンスが記載されていなければならない
Must require that the license appear on all copies of the software source code.
実行ファイルやその他のライブラリのバイナリ利用にライセンスの記載が必要であると求めてはならない
Must not require that the license appear with executables or other binary uses of the library.
実行ファイルやその他のライブラリのバイナリ利用にソースコードが必要であると求めてはならない
Must not require that the source code be available for execution or other binary uses of the library.
Boost webサイトにある標準バージョンについてのみライブラリの名前と説明を使うことができる、という制限を設けてもよい
May restrict the use of the name and description of the library to the standard version found on the Boost web site.
ライブラリのインターフェースは移植性があるものでなければならず、特定のコンパイラやOSへと制限されていてはならない。
ライブラリの実装は、可能であれば、移植性のあるものでなければならず、特定のコンパイラやOSへと制限されていてはならない。 もし移植性のある実装が不可能なら、移植性のない構築は許容される。もし他の環境へのportが妥当な容易さであるなら、 少なくとも二つのOS(例えばUNIXとWindows)への実装が提供される。
ISO標準規格に従わないC++コンパイラでコンパイルできることは要求されない。
ある特定の人気のあるC++コンパイラで必ずコンパイルできなければならない、ということは要求されない。 Boostの貢献者たちは、自分たちのライブラリが人気のあるコンパイラで動くか確かめようとすることが多い。 boost/config.hppconfiguration headerは コンパイラ依存性の回避方法についての推奨されるメカニズムである。
移植性を検証する絶対的な方法は存在しないので、boostへ投稿される多くのライブラリは、 二つのコンパイラ(多くの場合OSも異なる)でコンパイルし実行することで実際的な移植性を実演している。 そうしなければ、portが本当に実際上うまくいくのかレビュー担当者が疑問を持つようになる。
投稿しようとしているライブラリは本当にあなたが所有権をもっているものですか？ "How to Copyright Software" by MJ Salone, Nolo Press, 1990は以下のように書いている。
自分の時間を割いてやった仕事でも、それが会社で雇い主のためにやっているプログラミングと似通っているなら 法律上、厄介な問題を抱えることになるだろう。このような状況の時は、前もって雇い主から明文化されたリリースを得ておくのがよい。
投稿する全ての重要なファイルにcopyrightをつけよう。Boostは明示的なcopyright情報がないものは受け入れない。
ライブラリの投稿にあたって内容を準備するためのチェックリストとしてこのガイドラインをご利用ください。 全てのガイドラインが全てのライブラリに当てはまるわけではないが、従うおうとする努力に見合う内容だとおもう。
xml_parserとする。XML_parserとしない。)
// See http://www.boost.org/libs/foo for documentation.fooはaあなたのライブラリのディレクトリ名(下記参照)。
このコメントによって、Boostファイルを偶然見つけた人がドキュメントにアクセスするのが容易になる。また同時に、Boostのいくつかの自動化ツールは、
このコメントに依存してヘッダファイルの所属ライブラリを判別している。
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>
ライブラリの開発者は、Boostで経験を積むにしたがって 以下のような一貫した命名のアプローチがとても役に立つと考えるようになった。 サブディレクトリや名前空間を持つ大きなライブラリについては特に役に立つ。
どのようになっているのか説明するとしよう。 ライブラリは中身が分かるような名前を与えられる。暗号じみた省略は受け入れられない。 C++標準ライブラリでの作法に従って、名前は普通、複数形ではなく単数形である。 例えば、ファイルシステムを扱うライブラリなら、"filesystem"と命名され、"filesystems","fs","nicecode"という名前にはならないだろう。
ライブラリの最上位ディレクトリ(親にboost-root/libsがある)は、ライブラリと同じ名前を付けられる。例えば boost-root/libs/filesystem
ライブラリの最上位のヘッダディレクトリ(親にboost-root/boostがある)は、ライブラリと同じ名前を付けられる。例えば boost-root/boost/filesystem
ライブラリの最上位の名前空間(親に::boostがある)は、ライブラリと同じ名前を付けられる。例えば::boost::filesystem.
一番シンプルなライブラリでさえ、いくらかのドキュメントが必要だ。但し、量は必要に応じて変わってくるだろう。 ドキュメントは、読者がC++の基礎的な知識があることを前提とするが、エクスパートであることは前提としない。
ドキュメントのフォーマットはHTMLであり、高度なブラウザやサーバサイドの拡張を必要としてはならない。 スタイルシートは受け入れられる。ECMAScript/JavaScriptは受け入れられない。 ドキュメントの入り口は常に、index.html または index.htmでなければならない。 Redirectionを見よ。
ドキュメントの書き方は一つの正しい方法があるわけではない。 HTMLドキュメントは従来の印刷物とはかなり異なった方法で構成される。 Task-Orientedなスタイルはreference-orientedなスタイルとは異なる。 結局、こういう疑問がでてくる。 謎に包まれた「平均的な」C++プログラマとやらがうまくライブラリを使いこなすのに ドキュメントは十分だろうか？
ドキュメントのための適切な内容は以下のようなものだ。
もしドキュメントの書き方についてもっと知りたいなら Writing Documentation for Boostを見よ
要求事項とガイドラインのいくつかに関する論拠(rationale)
Exception specifications [ISO 15.4] は、投げられるかもしれない例外を示したり、あるいはプログラマがパフォーマンスを向上させる たいと願って、時々使われる。しかし以下のようなスマートポインタからのメンバを考えてみてほしい。
T& operator*() const throw() { return *ptr; }
この関数は他の関数を呼ばない。単にポインタのような基本型のデータを操作しているだけである。したがって 実行時には決して exception-specification のふるまいが引き起こされない。 この関数は完全にコンパイラに曝されていて、実際この関数はインラインとして宣言されている。 従って性能の良いコンパイラならすぐにこの関数が例外を投げることはないと見抜いて、exception-specificationのないときと同じ 最適化を行うことができるだろう。しかし、「駄目な」コンパイラでは悲惨なことになってしまう。
例えば、あるコンパイラはexception-specificationがあるとインライン化を中止する。 またあるコンパイラはtry/catchブロックを追加する。これでは実際のアプリケーションで 利用できないようなパフォーマンスの劣化につながる。
最初は魅力的に見えても、exception-specificationはとても注意して理解する必要のある結果を招きがちだ。 最大の問題はプログラマは自分に好ましいような結果を期待して利用するが、実際はなるようにしかならない、ということだ。
インラインでない関数なら、"どんな例外も投げない"exception-specification でも いくつかのコンパイラでいくらかの利益が得られるかもしれない。
C++標準化委員会のライブラリワーキンググループは この問題について詳細にわたるまで、長い期間議論した。 議論は初期のboostの投稿でも再度繰り返された。 以下は短いまとめである。
Dave Abrahamsのコメント：
ソースコードの最も重要な目的は（私は敢えて一番の目的だというが）コミュニケーションである。 すなわち意図のドキュメント化だ。これはboostにとって二重に重要だとおもう。
固定幅フォントの使用によって、(ダイアグラムのような)より多くの方法で ソースコードによるコミュニケーションが可能となる。 スペースと固定幅フォントによるコードは、可変長フォントで見てもそこそこうまく見える。
私の知る限り可変長のフォントをサポートするエディタは固定長フォントもサポートしている。 逆は真でない。
タブは禁止される。これは主義主張の上での好き嫌いとは関係ない。 Boostのような複数の開発環境を利用するプロジェクトで実際的な問題があるためである。 Boostメーリングリストのarchivesをみよ。 タブを使うプログラマとスペースを使うプログラマが一つのファイルをメンテナンスする場合、 一貫したタブのポリシーを強制するのが難しいのに比べて「タブ無し」というルールは簡単だ。 結局、Boostのファイル全てを、タブかスペースで統一すべきだということになった。そしてスペースが選ばれた。
1.29.0のリリース前に二つのBoostライブラリがECMAScript/JavaScriptのドキュメントを加えた。 議論は紛糾した。Boostメーリングリストのarchives そして開発者は、ECMAScript/JavaScriptを削除するように、ということになった。 禁止の理由には以下のようなものが含まれた。
Rationale という言葉は "The fundamental reasons for something; basis" と定義される。(the American Heritage Dictionary)
Beman Dawesのコメント
デザインの決定と同時にRationale(論拠)を決定できないことはソフトウエアプロジェクトにおける大きな欠点となる。
緻密なRationaleが存在しないと、終わりなき話題が何度も議題となり、
メンテナがそのコードの目的と方法を理解できないまま変更を行ってバグを生み出し、ソフトウエアの寿命を短くすることになる。
決定を下したときにRationaleを提供するのはたやすい。しかし少しでも後になると回復するのは難しい。
ライブラリが成熟するに従って、他のboostメンバからの指摘によって改善されてゆくのはよくあることだ。 貢献者を同定し、これらの貢献に対して謝意を示すのはboost.orgの文化の一部である。 大きな貢献はドキュメントに記され、小さな訂正はコード自体にコメントとして書き込まれる。
Revised 26 February, 2003
Japanese Translation Copyright (©) 2003 Satoshi Fujimoto
オリジナルの、及びこの著作権表示が全ての複製の中に現れる限り、この文書の複製、利用、変更、販売そして配布を認める。
このドキュメントは「あるがまま」に提供されており、いかなる明示的、暗黙的保証も行わない。また、いかなる目的に対しても、
その利用が適していることを関知しない。
Japanese Translation Last Revised: 4/29/2003