Annotation Support

Annotations enable you to extend and customize the analysis of your source code on top of the built-in rules in Team System's static Code Analysis engine. Annotations are written using the Structured Annotation Language (SAL) and were introduced into the product as a much requested feature within the developer community. The source code annotation API is contained in a header file called SourceAnnotations.h found in the C:\Program Files\Microsoft Visual Studio 8\VC\ include\CodeAnalysis directory. To include this library in your source code, simply use the #include pre-processor command, as shown here:

      #include <CodeAnalysis/SourceAnnotations.h>

In the CodeAnalysis directory, you will also find another header file called Warnings.h that lists all of the code analysis warnings supported in Team System (shown below). To find out the meaning of each warning code, please refer to the MSDN documentation included in Visual Studio.

      #pragma once #define ALL_CODE_ANALYSIS_WARNINGS 6001 6011 6014 6029 6031 6053 6054 6056 6057      6059 6063 6064 6066 6067 6200 6201 6202 6203 6204 6209 6211 6214 6215 6216 6217      6219 6220 6221 6225 6226 6230 6235 6236 6237 6239 6240 6242 6244 6246 6248 6250      6255 6258 6259 6260 6262 6263 6267 6268 6269 6270 6271 6272 6273 6274 6276 6277      6278 6279 6280 6281 6282 6283 6284 6285 6286 6287 6288 6289 6290 6291 6292 6293      6294 6295 6296 6297 6298 6299 6302 6303 6304 6305 6306 6307 6308 6309 6310 6312      6313 6314 6315 6316 6317 6318 6319 6320 6322 6323 6324 6326 6327 6328 6329 6331      6332 6333 6334 6335 6336 6381 6383 6384 6385 6386 6387 6388 6390 6391 6392 6393      6394 6400 6401 6411 6412 6500 6501 6502 6503 6504 6505 6506 6507 6508 6509 6510      6511 6512 6513 6514 6515 6516 6517 6518 6519 6520 6521 6522 6523 6524 6525 6526      6527 6530 6535 6990 6991 6992 6993 6994 6995 6996

Annotations provide you with important information about the return types and parameters of your functions. In fact, you can measure a variety of conditions, including testing for Boolean values, proper string formatting, pre- and post-conditions, and read/write conditions. Table 9-2 contains a complete list of the annotations that can be added to your source code.

Table 9-2

Attribute	Description
SA_Yes	This attribute indicates a positive outcome of a condition. For example, Null=SA_Yes is used to determine whether the function that is being tested returns a null value during pre- or post-instantiation.
SA_No	This attribute indicates a negative outcome of a condition.
SA_NoAccess	This attribute indicates a condition for which a function has no read/write access — for example, Access=SA_NoAccess.
SA_Read	This attribute indicates a condition for which a function has read access.
SA_Write	This attribute indicates a condition for which a function has write access.
SA_ReadWrite	This attribute indicates a condition for which a function has read and write access.
SA_Pre	This attribute indicates that a condition should be tested before a function is instantiated. For example: [SA_Pre(Null=SA_Yes)] SA_Pre and SA_Post are primarily used as containers to test conditions.
SA_Post	This attribute indicates that a condition should be tested after a function is instantiated. See the preceding description for an example.
SA_InvalidCheck	This attribute will check whether a function is returning a valid value, using the Value property.
SA_FormatString	This attribute will provide format information along with the Style property.

Working with annotations in C++

Annotations are written as follows in C++:

1. Include the SourceAnnotations.h file in your project using the following code:

         #include <CodeAnalysis/SourceAnnotations.h>

2. Use namespace vc_attributes and then define your custom class. The namespace will allow you to use multiple attribute types within your applications:

         using namespace vc_attributes;      class CustomClass{...}

Working with annotations in C

To work with annotations in C, you follow similar steps to those for C++ except that you don't have to use the using namespace vc_attributes. To add annotation support to your application, simply add the following include directive at the beginning of your code:

      #include <CodeAnalysis/SourceAnnotations.h>

Here is an example of simple C application with annotations:

      #include <CodeAnalysis/SourceAnnotations.h>      #include "customCode.h"      void t( [Post(Valid = SA_No)] int pCProg ){...}