これは、SDL Users Mailing Listに投稿された
「SDL 1.3 proposed conventions」
(Message-Id: E153qhs-0002iz-00@roboto.devolution.com)の和訳です。

原文: http://mail.lokigames.com/ml/sdl/14030.html

-----
Zinnia (zinnia@risky-safety.org)
http://ee5lance.ee5.yz.yamagata-u.ac.jp/~zinnia/


[和訳始め]----------------------------------------

私は経験ある開発者の皆様の意見を広く求めています。
毎度のことですが、フレーム(flame war)にしないでください。
そうなるようでしたら私は意見を求めるのを止めようと思います。

よろしく!

SDL1.3→2.0の書き直しについて以下のような規約を提案します。

APIに関する規約:
 
SDLの関数はbooleanまたはポインタの値を返す
SDLの関数は"SDL2_"あるいは"SDL_"といった接頭語を持つ
SDLの関数は第一引数にstatusポインタ(訳註: SDL_status)を持つ
statusポインタは0をとることができるが、いかなるエラー情報も保存されない。

例:

bool SDL2_Init(SDL_status *status, Uint32 flags);
SDL_VideoMode *SDL2_FirstVideoMode(SDL_status *status, Uint32 flags);
 
関数が0またはNULLポインタを返すとき 、エラーコードまたは文字列を
statusオブジェクトから得ることができる。

SDL_string *string;
 
switch (status->code) {
    case SDL_OUTOFMEMORY:
        /* ごみ集めをしてもう一度やってみる？ */
        break;
    default:
        string = SDL2_GetStatusString(status);
        ShowMessage("Operation Failed", string);
        break;
}
 
SDL_statuscode は、列挙可能な限りのエラーを含んだ列挙型のデータタイプ
です。個々のdriverが独自のエラーコードを追加できるように、
拡張可能なブロックを構成しています。(訳註: 具体的にどういう形なのかは
不明。原文は「These are organized into extendable blocks
so that individual drivers can add their own error codes.」です)
 
各々の関数プロトタイプは、戻り値、引数、driver非依存のエラーコードで
構成されたドキュメント部を持ちます。また、スレッド安全性(thread-safety)に
関する注意事項も記述される予定です。ドキュメント部は、ツールのパースを
簡潔にするために、/** で始まるコメントとなります。

コーディング規約: 

SDLのコードはANSI Cで書かれます。可読性を向上するため、
4スペース分のタブと、空行を適宜挿入します。
 
(訳註: 規約にはありませんがコメントは英語が望ましいと思われます。
       ここでは適当に和訳してみました)
/**
 SDL2_function - 何かをするのに便利な関数
 
 @param status
        Standard SDL status information
 @param param
        A parameter of some type
 @return a new object of some type
 
 この関数はなにか特別なことをしたいときに使われます。
 X、Y、Zに注意してください。あなたを驚かせることがあります。
 架空の関数についての説明を書くことがどのくらい無意味なことでしょうか？
 
 Thread-safety: この関数は完全にthread-safeです。
 
 @see SDL_status
**/

object *
SDL2_function(SDL_status *status, int param)
{
    /* このコメントはコードを明確化します */
    if ( internal_function(status) == failure )
        handle_failure(status);
    else
        handle_success();
 
    /*
     * C++スタイルのコメント(訳註: //で始まり行末で終わるコメントのこと
     * でしょう)はいくつかのコンパイラでエラーになります(訳註: そのため
     * 使うべきではないということでしょう)。
     * それから、1行の長さはできるだけ78文字におさめるようにしてください。
     */
    if ( (condition_one() == failure) ||
         (condition_two() == failure) ) {
        handle_failure(status);
    } else {
        handle_success();
    }
    return new_object;
}

みなさんはどう思われますか？ 良い？悪い？醜い？
くどいですが、建設的な意見を求めています。誰かの意見について良い意見を
持たないのでしたら、それを言わないでください!


See ya!
	-Sam Lantinga, Lead Programmer, Loki Software, Inc.


----------------------------------------[和訳終わり]