C/C++函数/方法装饰

Question

免责声明：我已经有一段时间没有使用 C++ 了……

现在为了提高可读性而装饰 C/C++ 函数/方法声明是否很常见？

粗略示例：

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

以及宏 IN 和 OUT 用空主体定义（即轻量级文档，如果您愿意在本例中使用）。当然，我知道这与与方法/函数关联的“文档注释块”有些并行。

您能否提供一些其他示例...假设该主题对社区有用。 请记住，上面的示例就是这样。

Answer 1

我不会欣赏这样的装饰。

使用 const 和引用以及常量引用会更好，就像

void some_function(AClass const ¶m1, AnotherClass ¶m2)

通常 int 是按值传递而不是按引用传递一样，所以我使用 AClass 和 AnotherClass 作为示例。
在我看来，添加 empy IN 和 OUT 会分散注意力。

Answer 2

Windows 标头实际上就是这样做的。有关完整列表，请参阅标头注释使用的注释。例如“

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

对于这个函数，hModule是一个可选的输入参数，lpFilename是一个输出参数，它最多存储nSize个字符元素，并且返回时会包含（函数的返回值）+1 个字符元素，nSize 为输入参数。

Answer 3

出于文档目的，编写良好的注释块就足够了，因此这些没有任何作用。此外，一些文档注释解析器有专门的语法来处理这样的事情；例如，给定 Doxygen，您可以编写：

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

Answer 4

我认为这是一个坏主意。特别是因为任何人都可以定义宏 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.

Answer 5

不是在 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<>用于单一所有权（通常作为来自工厂、本地或成员的返回值）。属性）...

Answer 6

我尝试使用：

• 输入参数或引用的值（如果它们很大）
• 输出参数的引用
• 赋予被调用函数所有权的指针

大多数时候很容易看出哪些是 IN 或 OUT 参数，当然还有声明中的正确名称是一个很好的文档。

我发现那些 IN、OUT 插件很烦人。

Answer 7

我见过这个，但我不认为我会说这是“常见”。

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 之类的声明，并在编译时进行检查。

Answer 8

唯一比这更糟糕的是很久以前在 Pascal dev 编写的 C 程序中看到的：

#define begin {
#define end   }

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

Answer 9

我以前没见过这个。我认为将这样的信息放在评论中会更好。

Answer 10

除了参数类型中的信息之外，我还看到了前缀 i_、o_、io_ 的使用：

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