Question

免责声明：我有一段时间没有做过C ++ ......

现在常见的是装饰C / C ++函数/方法声明以提高可读性吗？

原油示例：

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

使用空主体定义的宏 IN 和 OUT （例如，如果您将在此示例中使用轻量级文档）。当然，我理解这与与方法/功能相关的“doc注释块”并行。

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

Answer 1

我不会欣赏这样的装饰。

使用const和引用以及常量引用要好得多，比如

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

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

Answer 2

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

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＆lt;＆gt;对于稀释的共同责任（或在需要时），auto_ptr＆lt;＆gt; / unique_ptr＆lt;＆gt;单一所有权（通常作为工厂，当地人或成员属性的返回值）......

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开发的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);

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

10 个答案: