Cenni preliminari sull'annotazione
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. |