注釈の概要
注釈を使用すると、関数の動作を明示的に記述できます。 開発者は、機能上の注釈をソース コードに埋め込むことにより、実装側 (呼び出し先) と クライアント側 (呼び出し元) 間の決まりごとを明示的に記述できます。 コード分析ツールは、関数を呼び出す前および呼び出した後に関数パラメーターおよび戻り値の型の条件に関する追加情報を使用して、呼び出し元と呼び出し先の間で決められた規則の違反を検出します。 関数宣言に注釈を指定した場合は、関数定義でそれらを指定する必要はありません。
属性
注釈スキームは、VC++ コンパイラの属性として実装されています。 注釈の基本的な機能は、次の 2 つの属性によって実現されます。
Pre
Pre 属性を適用することによって、注釈の対象となる各パラメーターに対し、一連のプロパティを指定できます。 次の注釈では、Pre 属性に Valid プロパティが指定されています。
void f ( [ Pre (Valid = Yes) ] int pWidth);
この関数では、パラメーター pWidth に注釈を付けることにより、呼び出し元に、有効な整数値を渡すよう要求しています。 整数値または浮動小数値の場合、パラメーターはあらかじめ初期化され、ガベージ データが含まれていてはならないことを意味します。
Post
Post 属性を適用することによって、注釈の対象となる各パラメーターまたは戻り値に対し、一連のプロパティを指定できます。 次の注釈では、Post 属性に MustCheck プロパティが指定されています。
[returnvalue:Post(MustCheck=Yes)] bool f();
関数の戻り値に注釈を付けることにより、呼び出し元に、関数の戻り値を検査するよう要求しています。したがって、次のような呼び出しをすると、C6031 が生成されます。
void main( )
{
// code
f ( ); // warning 6031
// code
}
Pre 属性と Post 属性以外にも、次の 2 つの属性が用意されています。
FormatString 属性。書式情報を指定するために使用されます。 Style プロパティと組み合わせて使用します。
InvalidCheck 属性。関数の戻り値が有効か無効かを判断するために使用されます。 Value プロパティと組み合わせて使用します。
プロパティ
いくつかのプロパティを Pre 属性および Post 属性で指定できます。 ほとんどのプロパティは、Pre 属性と Post 属性のどちらでも使用できます。ただし、MustCheck プロパティについては、関数の戻り値に対してのみ適用でき、Post 属性で指定する必要があります。 特定のプロパティを使用する前に、ドキュメントをよく読んで、プロパティでサポートされる属性およびデータ型を確認しておいてください。 詳細については、「注釈のプロパティ」を参照してください。
C における注釈の使用
C のソース ファイルで注釈を使用するには、次のファイルをインクルードします。
#include <CodeAnalysis/SourceAnnotations.h>
次に、以下のコードにならって関数に注釈を付けます。
void f ([ SA_Pre (Valid = SA_Yes) ] int pWidth );
メモ C コードでは、属性および列挙値に対して SA_ プレフィックスを使用する必要があります。
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++ では、注釈を派生クラスから継承することはできません。