c++ - C/C++ 関数/メソッドの装飾

Question

免責事項: 私はしばらく C++ をやっていません...

読みやすさを向上させるために、C/C++ 関数/メソッド宣言を装飾することは最近一般的ですか?

大雑把な例:

void some_function(IN int param1, OUT char **param2);

空のボディで定義されたマクロINとOUTを使用します（つまり、この例では軽量のドキュメントです）。もちろん、これはメソッド/関数に関連付けられた「ドキュメントコメントブロック」と並行して行われることを理解しています。

他の例をいくつか挙げていただけますか...このトピックがコミュニティに役立つと仮定して. 上記の例はまさにそれであることに注意してください。

score 17 · Accepted Answer

私はそのような装飾に感謝しません。

次のように、const と参照と定数参照を使用する方がはるかに優れています。

void some_function(AClass const &param1, AnotherClass &param2)

通常、int は参照ではなく値で渡されるため、この例では AClass と AnotherClass を使用しました。空の IN と OUT を追加すると気が散るように思えます。

score 7 · Accepted Answer

Windows ヘッダーは実際にこれを行います。使用されている注釈の完全なリストについては、ヘッダー注釈を参照してください。例えば"

DWORD
WINAPI
GetModuleFileName(
    __in_opt HMODULE hModule,
    __out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
    __in DWORD nSize
    );

この関数の場合、hModuleはオプションの入力パラメーターでlpFilenameあり、は最大のnSize文字要素を格納し、戻り時に (関数の戻り値) + 1 文字要素を含むnSize出力パラメーターであり、入力パラメーターです。

score 6 · Accepted Answer

文書化の目的では、適切に記述されたコメントブロックで十分であるため、これらは何の役にも立ちません。さらに、一部のドキュメンテーションコメントパーサーには、まさにそのようなことのための特別な構文があります。たとえば、Doxygen が与えられた場合、次のように記述できます。

/**
 * @param[in]  param1 ...
 * @param[out] param2 ...
 **/
void some_function(int param1, char **param2);

score 4 · Accepted Answer

これは悪い考えだと思います。特に、誰でも来てマクロ IN/OUT を定義し、大きな問題に直面する可能性があるためです。

本当に文書化したい場合は、そこにコメントを入れてください。

void some_function(/* IN */ int param1, /* OUT */ char **param2);

また、戻り値が正常に機能する場合に out を使用するのはなぜですか。
また、自分の意図を示すために、ref と const ref によるパスを使用することをお勧めします。また、コードが const で正しい場合、コンパイラはインテントに対して比較的優れた最適化を行うようになりました。

void some_function(/* IN */ int const& param1, /* OUT */ char*& param2);
// OK for int const& is kind of silly but other types may be usefull.

score 2 · Accepted Answer

C++ ではなく、専門的に C プログラミングを行ったことはありませんが、少なくとも C++ では、パラメーターの型は一目瞭然です。

void f( std::string const & ); // input parameter
void f( std::string );         // input parameter again (by value)
void f( std::string& );        // in/out parameter
std::string f();               // output

それと、パラメーターにコンテキストを追加するコード内文書化ツール (doxygen) (関数によって期待される値または受け入れられない値、関数が渡されたオブジェクトをどのように変更するか...

ポインターについて: 私たちは、メソッドインターフェイスで生のポインターを制限する傾向があります。必要に応じて使用できますが、一般的にはスマートポインターを使用することをお勧めします。ここでも、所有権のセマンティクスはスマートポインターの選択から得られます。希薄化された共有責任 (または必要な場合) の場合は shared_ptr<>、単一の所有権の場合は auto_ptr<>/unique_ptr<> (通常はファクトリ、ローカル、またはメンバー属性からの戻り値として)。 ..

score 1 · Accepted Answer

Pascal dev によって書かれた C プログラムでこれがずっと前に見られたよりも悪い唯一のこと:


#define begin {
#define end   }

int main( int argc, char* argv[] )
begin
  ...
end

score 1 · Accepted Answer

私は使用しようとします：

入力パラメーターまたは参照の値が大きい場合
出力パラメーターのリファレンス
呼び出された関数に所有権を与えるポインタ

ほとんどの場合、どちらが IN パラメーターであるか OUT パラメーターであるかを簡単に確認できます。もちろん、宣言内の適切な名前は適切なドキュメントです。

IN、OUTのアドオンは面倒です。

score 1 · Accepted Answer

私はこれを見たことがありますが、「一般的」とは言えません。

Win32 API (C++ ではなく C) は、似たようなものを使用します。

WINADVAPI
BOOL
WINAPI
CreateProcessWithLogonW(
    __in        LPCWSTR lpUsername,
    __in_opt    LPCWSTR lpDomain,
    __in        LPCWSTR lpPassword,
    __in        DWORD dwLogonFlags,
    __in_opt    LPCWSTR lpApplicationName,
    __inout_opt LPWSTR lpCommandLine,
    __in        DWORD dwCreationFlags,
    __in_opt    LPVOID lpEnvironment,
    __in_opt    LPCWSTR lpCurrentDirectory,
    __in        LPSTARTUPINFOW lpStartupInfo,
    __out       LPPROCESS_INFORMATION lpProcessInformation
      );

Visual C++ 2005 以降のコンパイラの場合、これらは実際には次のような宣言にマップさ__$allowed_on_parameterれ、コンパイル時にチェックされます。

score 0 · Accepted Answer

パラメータタイプの情報に加えて、プレフィックス i_、o_、io_ の使用法を見ました。

void some_function(int i_param1, char** o_param2, int& io_param3);

score 0 · Accepted Answer

これは見たことがありません。このような情報はコメントに入れておいた方が良いと思います。

c++ - C/C++ 関数/メソッドの装飾

10 に答える 10

Related

Reference