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

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标题实际上正是这样做的.有关所用注释的完整列表,请参阅标题注释.例如"

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

对于此函数,hModule是一个可选的输入参数,lpFilename是一个输出参数,它存储最多的nSize字符元素,并且在返回时将包含(函数的返回值)+1个字符元素,并且nSize是输入参数.

但那些不是空的宏 - 最后,它们扩展到SAL属性,例如`[SA_Pre(...)]`和`[SA_Post(...)]`,它们实际上是由编译器处理的. (6认同)

Answer 3

出于文档目的,编写良好的注释块就足够了,因此这些注释块不能用于任何目的.此外,一些文档注释解析器只有这样的东西的特殊语法; 例如,给定Doxygen,你可以写:

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