Reasons to Use Source Code Annotations

There are several reasons to use source code annotations. In many cases, such annotations are preferable to using a script of LockLint subcommands.

• Annotations, being mixed in with the code that they describe, are generally better maintained than a script of LockLint subcommands.

• With annotations, you can make assertions about lock state at any point within a function--wherever you put the assertion is where the check occurs. With subcommands, the finest granularity you can achieve is to check an assertion on entry to a function.

• Functions mentioned in subcommands can change. If someone changes the name of a function from func1 to func2, a subcommand mentioning func1 fails (or worse, might work but do the wrong thing, if a different function is given the name func1).

• Some annotations, such as NOTE(NO_COMPETING_THREADS_NOW), have no subcommand equivalents.

• Annotations provide a good way to document your program. In fact, even if you are not using LockLint often, annotations are worthwhile just for this purpose. For example, a header file declaring a variable can document what lock or convention protects the variable, or a function that acquires a lock and deliberately returns without releasing it can have that behavior clearly declared in an annotation.