共用方式為

附註概觀

  • 發行項

更新：2007 年 11 月

附註可以讓函式明確地陳述其行為。程式開發人員可以將函式附註內嵌至原始程式碼中，明確地陳述「實作」(被呼叫端) 和「用戶端」(呼叫端) 之間的契約。程式開發人員所提供的函式參數和傳回值型別之 Pre 和 Post 條件的額外資訊，會由程式碼分析工具使用，偵測在呼叫端和被呼叫端之間的契約違規。如果在函式宣告上指定附註，就不需要在函式定義上指定。

屬性

附註配置會實作為 VC++ 編譯器 (Compiler) 屬性 (Attribute)。下列兩個屬性 (Attribute) 會提供附註的基礎：

  • Pre

每個 Pre 屬性 (Attribute) 的執行個體，會指定已加註之參數的一組屬性 (Property)。下列附註會使用 Pre 屬性 (Attribute) 和 Valid 屬性 (Property)：

void f ( [ Pre (Valid = Yes) ] int pWidth);

藉由加註 pWidth，函式會要求呼叫端傳遞有效的整數值。對於整數 (或浮點) 值，它表示參數已初始化而且不包含無用的資料。

  • Post

每個 Post 屬性 (Attribute) 的執行個體會指定已加註之參數或傳回值的一組屬性 (Property)。下列附註會以 Post 屬性 (Attribute) 和 MustCheck 屬性 (Property) 搭配使用：

[returnvalue:Post(MustCheck=Yes)] bool f();

藉由加註函式的傳回值，呼叫端必須檢查函式的傳回值，因此像下列的呼叫便會產生 C6031：

void main( )
{
  // code
  f ( ); // warning 6031
  // code 
}

除了 Pre 和 Post 屬性 (Attribute)，還有下列兩個可用的屬性 (Attribute)：

  • FormatString 屬性 (Attribute) 是用來指定格式資訊，會與 Style 屬性 (Property) 搭配使用。

  • InvalidCheck 屬性 (Attribute) 用來判斷函式的傳回值是否有效，會與 Value 屬性 (Property) 搭配使用。

屬性

有數個屬性 (Property) 可以和 Pre 與 Post 屬性 (Attribute) 一起指定。即使大多數的屬性 (Property) 可以同時在 Pre 和 Post 屬性 (Attribute) 上使用，MustCheck 屬性 (Property) 只能套用至函式的傳回值，並且必須和 Post 屬性一起指定。在使用特定的屬性 (Property) 之前，您應該閱讀說明文件以了解它所支援的屬性 (Attribute) 和資料型別。如需詳細資訊，請參閱附註屬性。

在 C 中使用附註

若要在 C 原始檔程式檔 (Source File) 中使用附註，請包含下列檔案：

#include <CodeAnalysis/SourceAnnotations.h>

接著加註函式，如下列程式碼所示：

void f ([ SA_Pre (Valid = SA_Yes) ] int pWidth );

注意 在 C 程式碼中，您必須在屬性 (Attribute) 和列舉值上使用 SA_ prefix。

在 C++ 中使用附註

在 C++ 中，在加入 #include <CodeAnalysis/SourceAnnotations.h> 檔後，加入下列命名空間：

using namespace vc_attributes;

接著加註函式，如下列程式碼所示：

void CMyClass::f ([ Pre (Valid = Yes) ] int pWidth )
注意事項：

在 C++ 程式碼中，您不須為列舉值使用 SA_ 前置字元，例如 Yes、No 和 Maybe。不過您必須在同時用於 C 和 C++ 程式碼的標頭中使用 SA_ 前置字元。在 C++ 中，附註無法由衍生的類別 (Class) 所繼承。

請參閱

參考

C6031