嵌入式开发：注释C代码的10个技巧

良好记录的源代码可以通过提供对软件的深入了解来减少设计成本和上市时间，否则需要时间和实验来唤起嵌入式开发人员对代码行为的内容和原因的记忆。如果失去了这些洞察力，还会增加成本，并通过将错误引入代码库来推迟上市时间。

在繁忙的开发周期中，注释C代码落到优先级列表的底部并不罕见。在将产品发布出去的压力下，纪律通常会失效，捷径会导致糟糕的代码库。这里有10个简单的技巧，你可以遵循它们来确保软件不仅被文档化，而且还包含有用的信息。

1、解释为什么，而不是如何

在开发软件时，人们似乎倾向于解释一行代码在做什么，而不是首先解释代码为什么会在那里。一个最受欢迎的例子是将文字移位x位。代码和注释通常看起来像这样

// Shift bit by 8 and store in PortB

*Gpio_PortB |= (1UL<<8);

这个评论本身就有很多不尽人意的地方。任何对C语言有基本了解的人通过观察都知道代码行在做什么，但是为什么我们要移动 8 位呢? 为什么我们要将移位的位模式存储到 PortB 中? 如果嵌入式开发人员在编写这行代码六个月或一年后阅读这行代码，如果不调查这一行代码到底在做什么，他将会一无所知。

更合适的情况可能如下所示:

// Port B bit 8 controls the motor relay that needs to be turned off during the

// emergency stop procedure. Setting bit 8 high will disengage the motor through a relay.

*Gpio_PortB |= (1UL<<8);

这个评论可能并不完美，但它解释了为什么开发人员将移位和按位或运算到PortB中。哪个评论更受欢迎?

2、编码前注释

注释代码的常识总是建议在编写代码的同时编写注释。这种见解很有道理;当编写软件时为什么开发人员对此记忆犹新。开发人员可以等到软件写完之后，但是推向市场的压力和其他优先考虑的事情通常使得注释很可能无法传达最初的意思。

在代码期间或之后编写注释的另一种方法是在编写软件之前编写注释，这有一个独特的优势，允许嵌入式开发人员在编写一行代码之前考虑他们将要编码的内容和原因，它可以被认为是将软件架构和开发的设计阶段转化为源代码，这种方法将软件设计放在开发人员的首要位置，并允许他们清楚地思考他们将要编写的代码是为了什么。

3、使用Doxygen标签

网上有许多不同的免费工具可以将代码注释转换成有用的文档格式。能够扫描源代码并生成html、rtf和/或pdf的工具应该是开发人员的梦想。为什么?许多开发团队不仅要维护他们的源代码，还要维护各种描述代码实际工作的设计文档。这些文档经常追踪程序中实际发生的事情。

使用工具，例如Doxygen可以自动将代码注释翻译成符合这些设计文档清单的文档。最终结果是，开发人员现在只需要维护一个源代码和文档链，这将减少他们创建“漂亮”文档所需的时间。(也希望确保文档和源代码彼此保持同步)。

Doxygen已经被广泛接受，以至于编译器和芯片供应商在其自动生成的代码中包含了Doxygen标签。他们将Doxygen构建到工具链中，以使开发人员更容易生成文档。作为开发人员，难道我们不应该接受这个让文档变得如此简单的免费工具吗?

4、采用代码风格指南

编码风格指南包含了开发人员正确创建标识符所需的所有信息，以及如何记录软件。风格指南有助于为嵌入式开发人员或开发团队提供以统一方式开发软件的方法。这种一致性有助于开发人员消除由于风格差异而可能存在的对软件的干扰。结果是代码评审更容易，因为代码的风格是统一的，评审可以集中在实际的代码上，而不是注释位置的表面细节。

5、使用文件头

强烈推荐使用版本控制系统，但是在代码库发生变化时总是参考版本控制系统会变得很乏味。有时可能会令人困惑或不清楚特定模块的目的是什么。基于这些原因，建议头文件和源文件包含一个注释头，描述模块的功能和用途。

标题中可以包含许多信息，但至少应包括：

文件名

作者

起始日期

模块版本号

用于编译代码的编译器版本

预期目标

版权信息

杂项说明

修订信息

……

6、创建评论模板

确保代码注释一致并遵守Doxygen语法的最佳方法之一是创建一个注释模板。嵌入式开发人员需要两个模板：一个用于头文件，另一个用于源文件。编码模板将包含遵循编码风格所需的所有标准注释块。

注释模板将包含一个文件头以及注释标签和注释块，用于结构、枚举，类型定义、和函数。

7、一致的评论位置

减少与软件项目相关的错误和成本的最有效的方法之一是执行代码评审。开发人员通常执行代码评审，但是如果注释结构不一致，这个过程会变得更加困难。使用不同格式并放在不同位置的注释会分散注意力，降低代码评审的效率。

推荐使用编码风格指南，因为它不仅规定了应该使用的注释格式，还规定了注释应该出现在哪里，这将有助于保持注释结构的统一，并允许代码审查者关注代码及其行为，而不是被注释中包含的位置或信息分散注意力。

8、不要注释每一行

老实说，开发者真的不想评论他们的软件。这既费时又不令人愉快。旋转位、控制硬件以及几乎做任何其他事情要有趣得多。然而，通常认为是文档记录良好的每一行代码都要有一个注释，这可能太多了。

注释代码的目的是为未来的嵌入式开发人员或维护人员提供关于软件是什么和为什么的洞察力。冗长的文章既不需要也不想要。创建一个注释块来描述这个块在做什么通常就足够了。对块进行注释的一个很大的好处是，如果代码需要更改，但是块描述仍然适用，那么描述可以保持不变，从而节省了开发时间，否则这些时间将会花费在更新注释上。

9、以类型开始数学类型标识符

当开发执行数学运算的软件时，以标识符的类型开始非常有用。例如，创建一个名为ui8_Velocity或si32_Acceleration的变量可以让开发人员立即了解变量的类型。

以这种方式命名标识符有很多优点。首先，不需要引用变量声明来获取类型。这可以节省时间，因为开发人员不必不断刷新变量的类型和大小，以及是否需要在计算中进行强制转换。第二，这种命名方式更容易发现转换错误，比如两个8位数字相乘而不进行转换。

10、进行代码更新时更新注释

如果使用得当，将模板与Doxygen结合使用会是一个非常强大的工具。这些模板和工具的正确使用部分来自于软件的更新和维护。只有当嵌入式开发人员足够自律，能够随着软件的变化更新他们的注释时，这些工具才有效。

在开发过程中，需求、设计和实现无疑会发生变化。作为这些变更的一部分，开发人员需要确保注释总是随着软件的实现而更新。即使事实并非如此感觉就像有足够的时间来实现代码更改和更新注释一样，开发人员仍然应该花时间来更新注释。一个原因是，在产品的整个生命周期中，它的成本将受到开发人员保持纪律的极大影响，尽管他们可能面临时间压力。

结论

评论软件通常被认为是开发周期中优先级最低的任务之一。快速实施和部署嵌入式软件的压力让工程师们不得不忙于设计、实施和部署他们的固件。但事实是，注释代码并阐明代码的原因可以使未来的维护工作甚至最初的开发工作花费更少。在适当的情况下甚至会减少上市时间。

这些技巧只是改进嵌入式软件设计周期的几个简单例子，通过使用模板、标准和自动化工具，并花时间解释软件的原因，减轻嵌入式开发人员的负担。