号外号外：无规矩不成方圆(3)

本文MISRA规则由嵌入式程序猿整理自网络，版权归原作者所有

今天我们来讲讲MISRA对文档的规则要求;

所有实现定义（implementation-defined）的行为的使用都应该文档化。

本规则要求，任何对实现定义的行为的依赖——这些行为在其他规则中没有特别说明的——都应该写成文档，例如对编译器文档的参考。如果一个特定的行为在其他规则中被显式说明了，那么只有那项规则在其需要时给出背离。

字符集和相应的编码应该文档化。

例如，ISO 10646 [22]定义了字符集映射到数字值的国际标准。出于可移植性的考虑，字符常量和字符串只能包含映射到已经文档化的子集中的字符。

应该确定、文档化和重视所选编译器中整数除法的实现。

当两个有符号整型数做除法时， ISO 兼容的编译器的运算可能会为正或为负。首先，它可能以负余数向上四舍五入（如， -5/3 = -1，余数为-2），或者可能以正余数向下四舍五入（如，-5/3 = -2，余数为+1）。重要的是要确定这两种运算中编译器实现的是哪一种，并以文档方式提供给编程人员，特别是第二种情况（通常这种情况比较少）。

所有#pragma 指令的使用应该文档化并给出良好解释。

这项规则为MISRA文档的使用者提供了产生其应用中使用的任何 pragma 的要求。每个 pragma的含义要写成文档，文档中应当包含完全可理解的对 pragma 行为及其在应用中之含义的充分描述。应当尽量减少任何 pragma 的使用，尽可能地把它们本地化和封装成专门的函数。

如果做为其他特性的支撑，实现定义（implementation-defined）的行为和位域（bitfields）集合应当文档化。

这是在使用了规则 6.4 和规则 6.5 中描述的非良好定义的位域时遇到的特定问题。 C 当中的位域是该语言中最缺乏良好定义的部分之一。位域的使用可能体现在两个主要方面：

为了在大的数据类型（同 union 一起）中访问独立的数据位或成组数据位。该用法是不允许的（见规则 18.4）。

为了访问用于节省存储空间而打包的标志（ flags）或其他短型（ short-length）数据。为了有效利用存储空间而做的短型数据的打包，是本文档所设想的唯一可接受的位域使用。假定结构元素只能以其名字来访问，那么程序员就无需设想结构体中位域的存储方式。我们建议结构的声明要保持位域的设置，并且在同一个结构中不得包含其他任何数据。

如果要使用位域，就得注意实现定义的行为所存在的领域及其潜藏的缺陷（意即不可移植性）。特别地，程序员应当注意如下问题：

• 位域在存储单元中的分配是实现定义（implementation-defined）的，也就是说，它们在存储单元（通常是一个字节）中是高端在后（high end）还是低端在后(lowend)的。
• 位域是否重叠了存储单元的界限同样是实现定义的行为（例如，如果顺序存储一个 6位的域和一个4 位的域，那么4 位的域是全部从新的字节开始，还是其中 2 位占据一个字节中的剩余 2 位而其他2 位开始于下个字节）。

产品代码中使用的所有库都要适应本文档给出的要求，并且要经过适当的验证。

本规则的对象是产品代码中的任意库，因此这些库可能包含编译器提供的标准库、其他第三方的库或者实验室中自己开发的库。这是由 IEC 61508 Part 3 建议的。