Übersicht über Anmerkungen
Mithilfe von Anmerkungen können Funktionen explizit ein Verhalten angeben. Entwickler können funktionale Anmerkungen in den Quellcode einbetten, um explizit die Verträge zwischen Implementierungen (Aufgerufenen) und Clients (Aufrufern) anzugeben. Anhand der zusätzlichen Informationen, die der Entwickler zu der Vor- und Nachbedingung der Funktionsparameter sowie zu den Rückgabetypen angibt, kann das Codeanalysetool Verletzungen des Vertrags zwischen dem Aufrufer und dem Aufgerufenen erkennen. Wenn Sie in der Funktionsdeklaration Anmerkungen angeben, müssen diese in der Funktionsdefinition nicht angegeben werden.
Attribute
Das Anmerkungsschema wird als VC++-Compilerattribute implementiert. Die folgenden beiden Attribute bilden die Basis für Anmerkungen:
- Pre
Jede Instanz eines Pre-Attributs gibt Eigenschaften für den Parameter mit Anmerkungen an. Bei der folgenden Anmerkung wird das Pre-Attribut mit der Valid-Eigenschaft verwendet:
void f ( [ Pre (Valid = Yes) ] int pWidth);
Da eine Anmerkung zum Parameter pWidth hinzugefügt wurde, muss der Aufrufer bei dieser Funktion einen gültigen Ganzzahlwert übergeben. Bei einem Ganzzahlwert oder auch einem Gleitkommawert bedeutet dies, dass der Parameter initialisiert wurde und keine veralteten Daten enthält.
- Post
Jede Instanz eines Post-Attributs gibt Eigenschaften für den Parameter oder Rückgabewert mit Anmerkungen an. In der folgenden Anmerkung wird das Post-Attribut mit der MustCheck-Eigenschaft verwendet:
[returnvalue:Post(MustCheck=Yes)] bool f();
Da dem Rückgabewert einer Funktion die Anmerkung hinzugefügt wurde, muss der Aufrufer den Rückgabewert der Funktion überprüfen. Aus diesem Grund wird durch einen Aufruf wie den folgenden C6031 generiert:
void main( )
{
// code
f ( ); // warning 6031
// code
}
Neben dem Pre-Attribut und dem Post-Attribut sind die folgenden beiden Attribute verfügbar:
Das FormatString-Attribut dient zum Angeben von Formatinformationen. Es wird mit der Style-Eigenschaft verwendet.
Mithilfe des InvalidCheck-Attributs wird ermittelt, ob der Rückgabewert einer Funktion gültig oder ungültig ist. Es wird mit der Value-Eigenschaft verwendet.
Eigenschaften
Mit dem Pre-Attribut und dem Post-Attribut können verschiedene Eigenschaften angegeben werden. Die meisten Eigenschaften können sowohl mit dem Pre-Attribut als auch mit dem Post-Attribut verwendet werden, die MustCheck-Eigenschaft jedoch kann nur auf den Rückgabewert der Funktion angewendet werden und muss daher mit dem Post-Attribut angegeben werden. Bevor Sie eine Eigenschaft verwenden, sollten Sie sich in der Dokumentation über die unterstützten Attribute und Datentypen informieren. Weitere Informationen finden Sie unter Anmerkungseigenschaften.
Verwenden von Anmerkungen in C
Um Anmerkungen in C-Quelldateien zu verwenden, schließen Sie die folgende Datei ein:
#include <CodeAnalysis/SourceAnnotations.h>
Fügen Sie danach der Funktion eine Anmerkung hinzu, wie im folgenden Code gezeigt:
void f ([ Pre (Valid = SA_Yes) ] int pWidth );
Hinweis In C-Code müssen Sie für aufgelistete Werte das SA_-Präfix verwenden, z. B. SA_Yes, SA_No, SA_Maybe, SA_NoAccess, SA_Read, SA_Write und SA_ReadWrite. Die Verwendung des SA_-Präfixes für Attribute in C-Code ist zwar optional, aber korrekt.
Verwenden von Anmerkungen in C++
Fügen Sie in C++ nach dem Hinzufügen der Datei #include <CodeAnalysis/SourceAnnotations.h> den folgenden Namespace hinzu:
using namespace vc_attributes;
Fügen Sie danach der Funktion eine Anmerkung hinzu, wie im folgenden Code gezeigt:
void CMyClass::f ([ Pre (Valid = Yes) ] int pWidth )
Hinweis
In C++-Code muss das SA_-Präfix für aufgelistete Werte nicht verwendet werden. Beispiele: Yes, No und Maybe. In einem Header, der sowohl für C-Code als auch für C++-Code verwendet werden soll, muss das SA_-Präfix jedoch verwendet werden. In C++ können Anmerkungen nicht von der abgeleiteten Klasse geerbt werden.