22、代码编写与安全保障的实用指南

代码编写与安全保障的实用指南

1. 代码可维护性与注释的艺术

代码的可维护性并非自动实现，即使是面向对象的代码，也需要程序员付出额外努力。在编写代码时，注释是一项重要的工作，但也需要遵循一定的原则。

1.1 注释的基本规则

多数编程风格指南源于一个基本规则：如果能用代码表达，就不要用注释。也就是说，若能在代码中清晰体现注释的核心内容，就应省略注释。不过，这并不意味着不写注释，而是要将注释留给那些无法用代码表达的重要思想。

1.2 注释的重点

注释应聚焦于解释代码的功能和目的，而非代码的实现方式，因为代码本身应能说明其工作原理。例如，对于每个程序单元（函数、类或模块），开头的注释应解释其功能，而不涉及实现细节。若无法在不解释实现方式的情况下说明程序单元的功能，这可能是该单元缺乏良好内聚性的警示信号。

1.3 函数注释示例

以一个 C 函数 compress 为例：

size_t compress(char *s, size_t n, char c);

可以这样注释：

'compress' removes all occurrances of character 'c' from character
array 's' of length 'n,' and shifts the remaining characters of 's' left
(to lower add