[SOLVED]「API 設計の原理原則」のレビューをお願いします。
-
"API Design Principles":http://developer.qt.nokia.com/wiki/API_Design_Principles を "日本語訳":http://developer.qt.nokia.com/wiki/API_Design_Principles_Japanese してみました。
誤訳や改善できる点がかなりあると思うので、レビューにご協力ください。
-
読んだところまでで、気付いた点を。ご参考程度に……。
良い API の６つの特徴
「API とはプログラマーにとってどのような GUI をエンドユーザーに届けるかということです。」
→「プログラマーにとって API とは、エンドユーザーにとっての GUI のようなものです。」「API の ‘P’ は “Program” ではなく “Programmer” を意味します。これは API は人間のプログラマーによって使われるという事実によるものです。」
→「API は人間のプログラマーによって使われるという事実を強調する場合、API の ‘P’ は “Program” ではなく “Programmer” を意味します。」完全であれ
「その機能にたどり着く可能性が低くなります。」
→「その関数に...」
the function は前の a member function を指すと思います。ですので、「機能」より「関数」の方が適当かと思います。「一般的なものは簡単に対応できるようにし、一般的ではないものにも対応できるようにしておきます。個々の問題への対処: 必要のないものには必要以上に対応しないようにしましょう(例えば、Qt 3 のQMimeSourceFactory は QImageLoader を呼び出し、異なる API を持つことができました)。」
→「一般的なものは簡単に対応できるようにします。一般的ではないものも対応できるようにすべきですが、それにはフォーカスしません。個々の問題への対処: 解決策を必要以上に一般化しないようにしましょう (例えば、Qt 3の QMimeSourceFactory は、QImageLoader と呼ばれる異なるAPI を持つものにすることもできました)。」QRegExp の例のところ
「このような API の実装では、内部のオブジェクトを柔軟に生成することがポイントです。例えば、QRegExp の場合、どのパターンのシンタックスかを知ること無しに setPattern() で指定された “.” のパターンをコンパイルするのは早計です。」
→「このような API の実装では、内部のオブジェクトが遅延するように生成することがポイントです。例えば、QRegExp の場合、パターンシンタックスが何になるかがわかる前に、 setPattern() で指定された “.”のパターンをコンパイルしてしまうのは時期尚早です。」「通常は(...ということを)チェックすべき点であり、この動作はドキュメントに正確に記載されるべきですが、問題はありません。」
→「通常はこれがチェックしたい点 (...ということ) なので、問題はありません。ただし、この動作はドキュメントに正確に記載されるべきですが。」ポインタか参照か
「値を変える場合には、ポインタと参照ではどちらがベストでしょうか？」
→「出力パラメーターには、...」
意図的に意訳した部分かと思いますが、この場合直訳した方がわかりやすい気がしました。「面白いことに(期待はしていませんでしたが)」
→「面白いことに(予期していなかったわけではないのですが)」「経験則では、我々のツールキットとそのクラスの主なユーザーがある関数を呼び出すような場合、その関数はおそらく非バーチャルであるべきです。」
→「経験則では、我々がツールキットとして、そして主なユーザーとして、関数を呼び出すような場合でない限り、その関数はおそらく非バーチャルであるべきです。」 -
続きです。一通り読んで気付いた点を、ご参考まで。
また、読んでの感想ですが、Qt3 / Qt4 の間で、API に対してどういった変更がどのような意図の元でされたか？についての説明が、大変勉強になり面白かったです。ありがとうございました。
戻り値の const
「そのメンバを直接操作することや、const ではないメンバ関数へのアクセス時のクラス型の R-value に “const” を追加することは禁止されています。」
→「クラス型の R-value に “const” を追加した場合、const ではないメンバ関数へアクセスすることや、そのメンバを直接操作することは禁止されています。」「“const” の追加によるそのようなアクセスはできませんが、ごく稀に R-value オブジェクトの有効期間に終わる変更が必要となる場合があります。」
→「“const” を追加しなければそういったアクセスもできますが、それが必要となるケースはごく稀です。なぜならば、加えた変更も R-value オブジェクトの有効期間の終了と共に消えてしまうからです。」戻り値: ポインタ vs const ポインタ
「“const の正しさ” のコンセプトが部分的に失敗していると感じるところです。」
→「“const の正しさ” のコンセプトが破綻していると感じるところです。」const vs オブジェクトの状態
「何の上に書くのかの状態を含みます。」
→「描画対象の状態を含みます。」一般的な命名規則
「少数の規則を全ての種類の命名に適用するのが良い方法です。」
→「どんな種類の名前にも上手く適用できる規則がいくつかあります。」「それでいて微妙なルールは」
→「それでいて繊細なルールは」Enum 型と値の命名
「enum の値が OR でまとめてフラグとして使用される可能性がある場合の伝統的な方法は、OR でまとめた結果を型安全ではない int に格納するものでした。」
→「enum の値を OR でまとめてフラグとして使用できる場合、その結果は int に格納するのが伝統的な方法ですが、これは型安全ではありません。」bool 型の引数の罠
「Qt 4 ではシンプルにウィジェットの背景の消去するという選択自体を削除しました。」
→「Qt 4 ではシンプルに、ウィジェットの背景を消去せずに描画するという選択自体を削除しました。」QProgressBar
「この API はとても複雑で矛盾しています。」
→「この API はとても複雑で一貫性に欠けています。」QAbstractItemModel
「重要な問題の１つは “QAbstractFoo” は単に考えうるすべての可能性を抽象化した基底クラスにすべきではなかったということです。」
→「一般化した教訓としては、“QAbstractFoo” は、考えうる全ての派生クラスから、単に和集合をとって作ればよいわけではないということです。」