Compartir a través de

Información general sobre anotaciones

  • Artículo

Actualización: noviembre 2007

Las anotaciones permiten que las funciones especifiquen el comportamiento de manera explícita. Los desarrolladores pueden incrustar anotaciones funcionales en el código fuente para especificar de manera explícita los contratos entre las implementaciones (destinatarios) y los clientes (llamadores). La herramienta de análisis de código utiliza la información adicional que el desarrollador proporciona sobre las condiciones Pre y Post de los parámetros y los tipos de valores devueltos de la función para detectar infracciones del contrato entre llamador y destinatario. Si se especifican las anotaciones en la declaración de función, no será necesario especificarlos en la definición de función.

Atributos

El esquema de la anotación se implementa como atributos del compilador de VC++. Los dos atributos siguientes proporcionan la base para la anotación:

  • Pre

Cada instancia de un atributo Pre especifica un conjunto de propiedades para el parámetro anotado. La anotación siguiente utiliza el atributo Pre con la propiedad Valid:

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

Al anotar el parámetro pWidth, la función exige a los llamadores que pasen un valor entero válido. Para un valor de integral o de coma flotante, significa que se ha inicializado el parámetro y no contiene los datos no utilizados.

  • Post

Cada instancia de un atributo Post especifica un conjunto de propiedades para el parámetro anotado o valor devuelto. La anotación siguiente utiliza el atributo Post con la propiedad MustCheck:

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

Al anotar el valor devuelto de una función, se exige al llamador que examine el valor devuelto de la función; por consiguiente, una llamada como la siguiente genera C6031:

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

Además de los atributos Pre y Post, están disponibles los dos atributos siguientes:

  • El atributo FormatString se proporciona para especificar información de formato. Se utiliza con la propiedad Style.

  • El atributo InvalidCheck se proporciona para determinar si un valor devuelto de una función es válido o no válido. Se utiliza con la propiedad Value.

Propiedades

Hay varias propiedades con las que se pueden especificar los atributos Pre y Post. Aunque la mayor parte de las propiedades se pueden utilizar en los atributos Pre y Post, la propiedad MustCheck sólo se puede aplicar al valor devuelto de la función y debe especificarse con un atributo Post. Antes de utilizar una propiedad determinada, debe leer la documentación para obtener información sobre los atributos y tipos de datos admitidos por ella. Para obtener más información, vea Propiedades de anotación.

Utilizar anotaciones en C

Para utilizar anotaciones en archivos de código fuente de C, incluya el archivo siguiente:

#include <CodeAnalysis/SourceAnnotations.h>

A continuación, anote la función como se muestra en el código siguiente:

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

Nota: en código de C, debe utilizar el prefijo SA_ en los atributos y valores enumerados.

Utilizar anotaciones en C++

En C++, después de agregar el archivo #include <CodeAnalysis/SourceAnnotations.h>, agregue el espacio de nombres siguiente:

using namespace vc_attributes;

A continuación, anote la función como se muestra en el código siguiente:

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

En el código de C++, no tiene que utilizar el prefijo SA_ para los valores enumerados, por ejemplo, Yes, No y Maybe. Sin embargo, debe utilizar el prefijo SA_ en encabezados que se vayan a utilizar para código de C y C++. En C++, la clase derivada no puede heredar las anotaciones.

Vea también

Referencia

C6031