SAL 注释，使用哪一个？答案

【问题标题】：SAL annotations, which one to use?SAL 注释，使用哪一个？
【发布时间】：2012-08-17 11:28:30
【问题描述】：

因此，我涉足了 C++ 的源代码注释，但发现有很多方法可以通向罗马，可以这么说。

例子：

__in

_In_

[Pre(FormatString(Style="printf")] LPCSTR format

是否有一种-microsoft-方法可以做到这一点？

【问题讨论】：

SAL 可能只对 C 有意义，对 C++ 没有意义。但考虑到微软甚至把MessageBox 的注释都弄错了。这意味着 SAL 比毫无价值的垃圾更糟糕：它增加了极大的冗长，从而减慢了程序员的速度，并且它传达的少量信息通常是错误的（如我的示例所示），因此不仅减慢了程序员的速度，而且还积极地误导了他们。因此，即使对于 C，我也会说使用 SAL 是非常适得其反。 就说不！
@Cheersandhth.-Alf 我不能代表用户态代码，但 SAL 实际上对驱动程序非常有益。特别是_IRQL 注释
@brc：嗯，我看过了。除了“SAL 是实现保证的唯一方法”这个问题之外，它看起来非常复杂，而中断请求级别本身就是一件简单的事情。所以它让我强烈地想起了微软的“公寓”增加了 COM 线程的复杂性方案。许多人认为这很有意义。许多人仍然认为WinMain（刚刚添加，适得其反的无意义复杂性）是个好主意。所以，我强烈怀疑 SAL _IRCL 注释也是如此：它们只是不必要地增加了复杂性和混淆。

【解决方案1】：

可能不会，因为 SAL 注释是一种元语言，可以帮助静态分析工具在编译时检查错误，我认为它可能依赖于编译器（至少在某种程度上用于复杂检查）因此，您可能没有一种方法适用于所有这些方法，但是从一种方法到另一种方法的转换并不太复杂

【讨论】：

【解决方案2】：

Microsoft 从 Windows 8¹ 开始引入了新的 SAL 标准 (SAL 2.0)。 SAL 2.0 使用单下划线样式的注解，例如_In_opt_among others。因此，对于所有新代码，最佳做法是遵循 SAL 2.0 样式，如 Microsoft 展示的 slides。

对于较旧的代码，“保持一致”的一般规则似乎是最好的方法，但如果您倾向于更新所有注释，请再次遵循 SAL 2.0 样式。

¹ - SAL 2.0 实际上自 2010 年以来就已经存在（查看链接演示文稿上的日期），但据我所知，直到 Windows 8 才得到外部官方支持。

【讨论】：