Cenni preliminari sull'annotazione
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). Lo strumento di analisi del codice utilizza le informazioni aggiuntive sulle condizioni dei parametri di funzione e i tipi restituiti prima e dopo la chiamata della funzione 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 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.