Condividi tramite

Cenni preliminari sull'annotazione

  • Articolo

Aggiornamento: novembre 2007

Le annotazioni consentono alle funzioni di dichiarare esplicitamente il comportamento. Gli sviluppatori possono incorporare annotazioni funzionali nel codice sorgente per dichiarare esplicitamente i contratti tra le implementazioni (chiamati) e i client (chiamanti). Le ulteriori informazioni fornite dallo sviluppatore sulle condizioni Pre e Post dei parametri di funzione e dei tipi restituiti vengono utilizzate dallo strumento di analisi del codice per rilevare le violazioni del contratto tra il chiamante e il chiamato. Se si specificano annotazioni sulla dichiarazione di funzione, non sarà necessario specificarle sulla definizione di funzione.

Attributi

Lo schema di annotazione viene implementato come attributi del compilatore VC++. I due attributi riportati di seguito sono alla base dell'annotazione.

  • Pre

Ogni istanza di un attributo Pre specifica un insieme di proprietà per il parametro annotato. L'annotazione che segue utilizza l'attributo Pre con la proprietà Valid:

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

Annotando il parametro pWidth, la funzione richiede ai chiamanti di passare un valore integer valido. Per un valore integrale, o a virgola mobile, ciò significa che il parametro è stato inizializzato e non contiene dati errati.

  • Post

Ogni istanza di un attributo Post specifica un insieme di proprietà per il parametro annotato o per il valore restituito. L'annotazione seguente utilizza l'attributo Post con la proprietà MustCheck:

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

Attraverso l'annotazione del valore restituito di una funzione, al chiamante viene richiesto di esaminare il valore restituito della funzione. Pertanto, una chiamata simile a quella riportata di seguito genera C6031:

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

Oltre agli attributi Pre e Post, sono disponibili anche i due attributi seguenti:

  • L'attributo FormatString viene fornito per specificare informazioni sul formato ed è utilizzato con la proprietà Style.

  • L'attributo InvalidCheck viene fornito per determinare se un valore restituito di una funzione è valido o meno ed è utilizzato con la proprietà Value.

Proprietà

Esistono diverse proprietà che è possibile specificare con gli attributi Pre e Post. Sebbene molte proprietà possano essere utilizzate su entrambi gli attributi Pre e Post, MustCheck può essere applicata solo al valore restituito della funzione e deve essere specificata con un attributo Post. Prima di utilizzare una determinata proprietà è necessario leggere la documentazione in cui vengono illustrati gli attributi e i tipi di dati che supporta. Per ulteriori informazioni, vedere Proprietà di annotazione.

Utilizzo dell'annotazione in C

Per utilizzare le annotazioni nei file di origine C, includere il seguente file:

#include <CodeAnalysis/SourceAnnotations.h>

Annotare quindi la funzione, come illustrato nel codice riportato di seguito:

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

Nota   Nel codice C è necessario utilizzare il prefisso SA_ per gli attributi e i valori enumerati.

Utilizzo dell'annotazione in C++

In C++, dopo aver aggiunto il file #include <CodeAnalysis/SourceAnnotations.h>, aggiungere lo spazio dei nomi seguente:

using namespace vc_attributes;

Annotare quindi la funzione, come illustrato nel codice riportato di seguito:

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

Nel codice C++ non è necessario utilizzare il prefisso SA_ per i valori enumerati, ad esempio Yes, No e Maybe. È tuttavia necessario utilizzare il prefisso SA_ in un'intestazione utilizzata sia per il codice C che C++. In C++ le annotazioni non possono essere ereditate dalla classe derivata.‎

Vedere anche

Riferimenti

C6031