【VS2022】Microsoft 源代码注释语言 SAL

$Microsoft$ 源代码注释语言 $SAL$

/**
 * @file            
 * @author			jUicE_g2R(qq:3406291309)————彬(bin-必应)
 *						通信与信息专业大二在读	
 * 
 * @brief			Microsoft 源代码注释语言 SAL
 * 
 * @copyright		2023.10
 * @COPYRIGHT			 原创技术笔记：转载需获得博主本人同意，且需标明转载源
 *
 * @language        C/C++
 *
 * @IDE			   Base on Microsoft Visual Studio 2022
 */

jUicE_g2R的个人主页

快速传送到 Microsoft 官方教程

1 定义

$Microsoft$ 源代码注释语言 ( $SAL$ ) 提供一组描述函数如何使用其参数的注释，有关注释的假设以及完成注释时的保证。 注释是在头文件 中定义的。

#include 

同时它也叫：代码安全增强 与 标准注解 语言

2 简述作用

$Microsoft$ 教程原话是：

1） $SAL$ 是让编译器为你检查代码的一种低成本的方法

2）使用 $SAL$ 注释减少代码缺陷

其实就是提高 $Debug$ 的效率！！！

其次，使用了 $SAL$ 相当于给代码后面添加的注释一样，只不过面向不是其他人，而是编译器（$Microsoft$ 教程原话是：编译器无法读取文档或非正式注释）

2-1 举个栗子

memcpy 将源缓冲区中的 count 个字节复制到目标缓冲区：

不使用 $SAL$

void * memcpy(
   void *dest,
   const void *src,
   size_t count
);

此时编译器不知道传入的参数有什么作用。

使用 $SAL$

void * memcpy(
   _Out_writes_bytes_all_(count) void *dest,		//参数是只读的，不进行修改
   _In_reads_bytes_(count) const void *src,			//参数是只写的
   size_t count
);

不懂继续看下面的表

2-2 $SAL$ 的检错能力

_Out_writes_bytes_all_(count)						//count向编译器注明了参数的空间大小

$(count)$ 注明了空间范围，这对编译器检查 $空间溢出$ 这种 $Bug$ 的效率无疑大大提高了。

$空间溢出$ 的问题可能存在于 数组在遍历时读过头了 ，正式点叫：差一错误（BUG: $OFF-BY-ONE$ ERROR）

3 四种基本类型的参数 —— 对 $形参$ 的注释

类别	参数注释	说明
输入到调用的函数	_In_	数据传递给调用的函数，并被视为只读。
输入到调用的函数并输出到调用方	_Inout_	可用数据传递到函数中，并可能进行修改。
输出到调用方	_Out_	调用方只为调用的函数执行写入操作提供空间。 调用的函数将数据写入该空间。
指针输出到调用方	_Outptr_	与“输出到调用方”一样。 调用的函数返回的值是一个指针。

下表显示了如何区分必需参数和可选参数：

	参数为必需参数	参数为可选参数
输入到调用的函数	_In_	_In_opt_
输入到调用的函数并输出到调用方	_Inout_	_Inout_opt_
输出到调用方	_Out_	_Out_opt_
指针输出到调用方	_Outptr_	_Outptr_opt_

这些注释帮助以正式且准确的方式识别可能的未初始化值和无效空指针的使用。 将 NULL 传递给必需参数可能会导致崩溃，或者可能会导致返回“失败”错误代码。 无论哪种情况，函数都无法成功完成其工作。

3-1 参数注释的区别

	_In_	_In_opt_
可否修改	否	否
可否接受空指针	否	可

_Out_ 与 _Out_opt_ ，_Inout_ 与 _Inout_opt_ ，_Outptr_ 与 _Outptr_opt_ 的关于空指针（$NULL$）的接受性区别同理

3-2 Outptr

面向 $指针$ 的注释，以 _Outptr_ 不可接受空指针的范例展示其应用

void GoodOutPtrCallee(_Outptr_ int **pInt)
{
   int *pInt2 = new int;						//为（局部）指针的指向对象分配内存空间
   *pInt2 = 5;								   	//给（局部）指针的指向对象赋值
   *pInt = pInt2;								//赋地址，pInt也指向pInt2的指向对象
}

void BadOutPtrCallee(_Outptr_ int **pInt)
{
   int *pInt2 = new int;
   // Did not initialize pInt buffer before returning!
   *pInt = pInt2;
}

void OutPtrCaller(void)
{
   int *pInt = NULL;							//pInt：地址变量
   GoodOutPtrCallee(&pInt);						//传入指针的地址
   BadOutPtrCallee(&pInt);
}

4 对 $形参$ 的注释

可以对 函数 的 $返回值$ $retval$ 进行注释

典型的栗子： $retval$ 的类型是 $bool$ 型的

_Success_ 注释与 _Out_ 组合：

_Success_(return != false) // Can also be stated as _Success_(return)
bool GetValue(_Out_ int *pInt, bool flag)
{
   if(flag) {
      *pInt = 5;
      return true;
   } else {
      return false;
   }
}

当它为 $true$ 时，指示函数已成功

5 哪些情况添加 $SAL$ 是必要

• 所有指针参数
• 提供值范围注释（如数组，容器一类）