Общие сведения о заметках

Обновлен: Ноябрь 2007

Заметки обеспечивают возможность явного обозначения работы функций. Разработчики могут встроить заметки к функциям в исходный код для явного обозначения контрактов между реализациями (вызываемыми объектами) и клиентами (вызывающими объектами). Дополнительные сведения, предоставляемые разработчиком о пред- и постусловиях параметров функций и возвращаемых типов, как правило, используются средством анализа кода для выявления нарушений контракта между вызывающим и вызываемым объектами. Если заметки заданы в объявлении функции, в определении функции задавать их уже не нужно.

Атрибуты

Схема заметок реализована в виде атрибутов компилятора VC++. Следующие два атрибута создают основу для заметок:

• Pre (пред)

Каждый экземпляр предатрибута задает набор свойств для параметра, к которому создается заметка. В следующей заметке используется предатрибут со свойством Valid:

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

Если параметр pWidth имеет заметку, функция требует передачи вызывающими объектами допустимого целого значения. Для целого значения — или значения с плавающей запятой — это означает, что параметр прошел инициализацию и не содержит ненужных данных.

• Post (пост)

Каждый экземпляр постатрибута задает набор свойств для параметра, к которому создается заметка, или для возвращаемого значения. В следующей заметке используется постатрибут со свойством MustCheck:

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

Если заметка создается к возвращаемому значению функции, вызывающему объекту необходимо проверить возвращаемое значение функции; таким образом, вызов следующего типа вырабатывает C6031:

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

Помимо пред- и постатрибутов доступны следующие два атрибута:

• Атрибут FormatString задает сведения о формате. Он используется со свойством Style.

• Атрибут InvalidCheck определяет допустимость возвращаемого значения функции. Он используется со свойством Value.

Свойства

Существует ряд свойств, которые могут задаваться с пред- и постатрибутами. Хотя большинство свойств могут использоваться как с пред-, так и с постатрибутами, свойство MustCheck может применяться только к возвращаемому значению функции и должно использоваться с постатрибутом. Перед использованием определенного свойства следует ознакомиться с документацией, чтобы узнать, какие атрибуты и типы данных оно поддерживает. Дополнительные сведения см. в разделе Свойства заметок.

Использование заметок в C

Для использования заметок в файлах с исходным кодом C добавьте следующий файл:

#include <CodeAnalysis/SourceAnnotations.h>

Затем создайте заметку к функции, как показано в следующем примере кода:

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

Примечание.   В коде C использование префикса "SA_" с атрибутами и значениями перечисления является обязательным.

Использование заметок в C++

В C++ после добавления файла #include <CodeAnalysis/SourceAnnotations.h> добавьте следующее пространство имен:

using namespace vc_attributes;

Затем создайте заметку к функции, как показано в следующем примере кода:

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

Примечание.
В коде C++ использование префикса "SA_" со значениями перечисления, такими как "Yes", "No" и "Maybe", является необязательным. Однако использование префикса "SA_" в заголовке, который будет использоваться и для кода C, и для кода C++, обязательно. В C++ заметки производным классом не наследуются.

См. также

Ссылки

C6031