C / C ++関数/メソッド装飾

StackOverflow https://stackoverflow.com/questions/1645978

  •  22-07-2019
  •  | 
  •  

質問

免責事項：C ++をしばらく使用していません...

最近、読みやすさを改善するためにC / C ++関数/メソッド宣言を修飾することは一般的ですか？

粗雑な例：

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

IN および OUT の empty 本文で定義されたマクロ（つまり、この例の場合は軽量のドキュメント）もちろん、これは<！> quot; doc comment block <！> quot;と並行して行われることを理解しています。メソッド/関数に関連付けられています。

このトピックがコミュニティに役立つと仮定して、他の例をいくつか教えてください。 お願い上記の例は単なる例であることに留意してください。

役に立ちましたか？

解決

このような装飾は好ましくありません。

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

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

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

他のヒント

Windowsヘッダーは実際にこれを正確に行います。完全なリストについては、ヘッダーアノテーションをご覧ください。使用される注釈。たとえば、<！> quot; 

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

この関数では、hModuleはオプションの入力パラメーター、lpFilenameは最大nSize文字要素を格納し、（関数の戻り値）+1文字要素を含む出力パラメーターです戻り時、および<=>は入力パラメーターです。

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

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

これは悪い考えだと思います。特に、だれでもやって来てマクロIN / OUTを定義でき、大きなトラブルに巻き込まれる可能性があるからです。

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

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

また、戻り値が正常に機能する場合にoutを使用する理由。
また、pass by 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.

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<！> lt; <！> gt;希薄な共有責任の場合（または必要な場合）、auto_ptr <！> lt; <！> gt; / unique_ptr <！> lt; <！> gt;単一所有権の場合（通常は、工場、ローカル、またはメンバー属性からの戻り値として）...

使用しようとしています：

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

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

これらのIN、OUTアドオンは迷惑です。

これは見たことがありますが、<！> quot; common。<！> quot;

とは思いません。

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などの宣言にマップされ、コンパイル時にチェックされます。

これよりも悪いのは、Pascal devによって書かれたCプログラムでずっと前に見られたものです：


#define begin {
#define end   }

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

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

パラメータタイプの情報に加えて、接頭辞i_、o_、io_の使用を見ました：

void some_function(int i_param1, char** o_param2, int& io_param3);
ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top