SAL - pipped at the post by Michael Howard.
I've been spending some time this week in the evenings thinking on how I should introduce SAL - the Standard Annotation Language - to you all. Then Michael Howard managed to do it before I could get there.
It's been in use at Microsoft for some time now, albeit frequently rather grudgingly. I was introduced to it as a Longhorn Quality Gate - something that had to be done in order to get a piece of software approved for checking in to the Longhorn Source Control tree.
Some teams choose to have everyone add SAL annotations to their own code; others do as our team did, and assign one or two people to learn SAL as much as they can before applying annotations to every piece of code under that team's ownership.
I very quickly discovered that, while SAL was indeed a pain in the neck to add to your code, it forcibly removes a lot of bad coding from your source tree, because there are some things that just cannot be SAL-annotated correctly - and those constructs are the ones that cause the most buffer overflows.
An example of such a construct? Sure - strcpy(). It's been the single biggest source of buffer overflows, either in reading when the string is not null-terminated, or in writing, when the destination buffer is shorter than the source. You just can't properly SAL-annotate strcpy, because you don't know the sizes of either of the strings, so you're forced to re-write it appropriately (and you get something like strcpy_s).
So can I add anything to Mike's descriptions of SAL?
Yes - mainly just this: if you cannot find a way to specify the type in SAL, you probably should think about defining your types using typedefs, rather than inlining the whole type definition. SAL definitions carry on through a typedef - for examples, look in WinNT.h, where you'll find definitions like PZPCWSTR: "typedef __nullterminated PCWSTR *PZPCWSTR;"
Finally, make sure that you use the same SAL annotation in the header file as you do in the C/CPP file. Otherwise, you'll get counter-intuitive results from the /analyze switch.
If you have any questions about SAL, please post them as comments below, or email me using the "Contact" link in the top right of this blog page.