Partager via

Vue d'ensemble de l'annotation

  • Article

Mise à jour : novembre 2007

Les annotations permettent aux fonctions de déclarer explicitement le comportement. Les développeurs peuvent incorporer des annotations fonctionnelles dans leur code source pour déclarer explicitement les contrats entre les implémentations (appelés) et les clients (appelants). Les informations supplémentaires fournies par le développeur à propos des conditions Pre et Post des paramètres de fonction et des types de retour sont utilisées par l'outil d'analyse du code pour détecter les violations du contrat entre l'appelant et l'appelé. Si vous spécifiez des annotations sur la déclaration de la fonction, il n'est pas nécessaire de les spécifier sur la définition de la fonction.

Attributs

La méthode d'annotation est implémentée comme attributs du compilateur VC++. Les deux attributs suivants fournissent la base de l'annotation :

  • Pre

Chaque instance d'un attribut Pre spécifie un ensemble de propriétés pour le paramètre annoté. L'annotation suivante utilise l'attribut Pre avec la propriété Valid :

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

La fonction requiert que les appelants passent une valeur entière valide en annotant le paramètre pWidth. Pour une valeur intégrale (ou à virgule flottante), cela signifie que le paramètre a été initialisé et ne contient pas de données incorrectes.

  • Post

Chaque instance d'un attribut Post spécifie un ensemble de propriétés pour le paramètre annoté ou la valeur de retour. L'annotation suivante utilise l'attribut Post avec la propriété MustCheck :

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

En annotant la valeur de retour d'une fonction, l'appelant est tenu de l'examiner ; par conséquent, un appel comme celui ci-après génère C6031 :

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

Outre les attributs Pre et Post, les deux attributs suivants sont disponibles :

  • L'attribut FormatString est fourni pour spécifier les informations de format. Il est utilisé avec la propriété Style.

  • L'attribut InvalidCheck est fourni pour déterminer si une valeur de retour d'une fonction est valide ou non. Il est utilisé avec la propriété Value.

Propriétés

De nombreuses propriétés peuvent être spécifiées avec les attributs Pre et Post. Bien que la plupart des propriétés puissent être utilisées sur les attributs Pre et Post, la propriété MustCheck peut être appliquée uniquement à la valeur de retour de la fonction et doit être spécifiée avec un attribut Post. Avant d'utiliser une propriété particulière, vous devez lire la documentation pour connaître les attributs et les types de données qu'elle prend en charge. Pour plus d'informations, consultez Propriétés d'annotation.

Utilisation de l'annotation en C

Pour utiliser les annotations dans les fichiers sources C, incluez le fichier suivant :

#include <CodeAnalysis/SourceAnnotations.h>

Ensuite, annotez la fonction comme indiqué dans le code suivant :

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

Remarque : dans le code C, vous devez utiliser le préfixe SA_ sur les attributs et les valeurs énumérées.

Utilisation de l'annotation en C++

En C++, une fois que vous avez ajouté le fichier #include <CodeAnalysis/SourceAnnotations.h>, ajoutez l'espace de noms suivant :

using namespace vc_attributes;

Ensuite, annotez la fonction comme indiqué dans le code suivant :

void CMyClass::f ([ Pre (Valid = Yes) ] int pWidth )
Remarque :

Dans le code C++, il n'est pas nécessaire d'utiliser le préfixe SA_ pour les valeurs énumérées, par exemple, Yes, No et Maybe. Toutefois, vous devez utiliser le préfixe SA_ dans un en-tête qui sera utilisé pour le code C et C++. En C++, les annotations ne peuvent pas être héritées par la classe dérivée.

Voir aussi

Référence

C6031