Windows SDK 参数注释答案

【问题标题】：Windows SDK parameter annotationsWindows SDK 参数注释
【发布时间】：2011-03-20 09:24:29
【问题描述】：

我想知道在 C++ 中进行 Windows 开发时使用注释是否重要？例如，

#include <windows.h>
int WINAPI WinMain(
    __in HINSTANCE hInstance,
    __in HINSTANCE hPrevInstance,
    __in LPSTR lpCmdLine,
    __in int nCmdShow
){
    return 0;
}

这可以写成：

#include <windows.h>
int WinMain(
    HINSTANCE hInstance,
    HINSTANCE hPrevInstance,
    LPSTR lpCmdLine,
    int nCmdShow
){
    return 0;
}

不使用它们会失去什么？我很难弄清楚这些是做什么用的，似乎没有任何为凡人编写的指南。

【问题讨论】：

你应该编辑标题，__in 与调用约定无关。调用约定（__stdcall、__fastcall、__cdecl）同时适用于所有参数。

标签： c++ c windows

【解决方案1】：

您必须使用旧版本的 SDK。 7.0 版声明的参数如下：

WinMain (
    __in HINSTANCE hInstance,
    __in_opt HINSTANCE hPrevInstance,
    __in LPSTR lpCmdLine,
    __in int nShowCmd
    );

注意 __in_opt 注释，它将参数标记为可选，表明传递 NULL 是可以接受的。这些是 SAL 注释的早期版本，是 Source code Annotation Language 的首字母缩写。他们有一个MSDN article，但是它记录了 C/C++ 库#include 文件中使用的语法。不太清楚为什么 SDK 组不使用相同的，他们往往赶上有点慢。

除了使声明更具可读性、消除 C 声明的歧义之外，注释对工具也很有用。很好的例子是内置在 VS2008 和 VS2010 的更高 SKU 中的代码分析器（它可以捕获编程错误）。还有 P/Invoke Interop Assistant，这是一个使用从带注释的 SDK 头文件生成的 dbase 生成 C# 或 VB.NET p/invoke 声明的工具。注释对于生成良好的 C# 声明至关重要。

您也可以在自己的代码中使用这些注释，如果您这样做，代码分析器会自动对其进行验证。请使用 MSDN 文章中记录的现代语法。我认为所需的 sal.h 标头几乎可以包含在任何 #includes CRT 标头的源文件中。

【讨论】：

【解决方案2】：

注释是您添加到源代码（例如 __in、__out 和 __inout）中的标记，它们为开发人员和静态分析工具提供有关函数及其参数及其预期用途的附加信息。注释就像添加到代码中的 cmets，编译器会忽略它，但静态分析工具会使用它们。注释的使用有助于提高开发人员的效率，有助于提高静态分析结果的准确性，并允许工具更好地确定是否存在特定错误。

来源：http://msdn.microsoft.com/en-us/library/ff550230%28VS.85%29.aspx

关于WINAPI 的事情见http://unixwiz.net/techtips/win32-callconv.html

【讨论】：

【解决方案3】：

IIRC，__in 和 __out 关键字是 #defined 没有。它们只是为了阐明每个参数的用途。 __in 参数被设计为被函数读取但不被修改，而__out 参数被设计为被函数修改以返回一些返回码。

您可以将__in 视为“通过const 引用传递”或“通过值传递”的C++ 思想，将__out 视为“通过非const 引用传递”。这不是字面上的意思，但它具有相同的内涵。

【讨论】：