Windows SDK參數註釋

Question

我想知道在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; 
} 

什麼我不使用他們失去？我很難搞清楚這些是爲了什麼，似乎沒有任何爲凡人寫的指南。

Answer 1

您必須使用舊版本的SDK。 7.0版聲明的參數是這樣的：

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

注意__in_opt註解，它標誌着參數爲可選，表明傳遞NULL是可以接受的。這些是SAL註釋的早期版本，是源代碼註釋語言的首字母縮略詞。他們有一個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頭文件被包含在任何包含CRT頭文件的源文件中。

Answer 2

註釋是添加到您的源代碼標記（如__in，__out和__inout），提供開發商和靜態分析工具提供有關函數及其參數，及其用途的其他信息。註釋類似於添加到代碼中的註釋，被編譯器忽略，但被靜態分析工具使用。註釋的使用有助於提高開發人員的效率，有助於提高靜態分析結果的準確性，並允許工具更好地確定是否存在特定的錯誤。

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

關於WINAPI事情看http://unixwiz.net/techtips/win32-callconv.html

Answer 3

IIRC的__in和__out關鍵字#define d不了了之。他們只是爲了澄清每個參數的目的。 __in參數被設計爲被函數讀取但未被修改，而__out參數被設計爲被函數修改以傳回一些返回碼。

你能想到的__in作爲C++的「通過const引用傳遞」或和__out「按值傳遞」的想法「通過非const引用傳遞」。這不是字面上的意思，但它有相同的內涵。