嵌入式开发：记录嵌入式软件的10个技巧

在软件开发中，没有什么比获得一个几乎没有文档并且需要维护它的代码库更具挑战性的了。文档不仅告诉工程师特定函数或变量的作用，而且还演示和传达了软件以特定方式实现的原因。在构建软件时会做出数百万个决策，对于嵌入式开发人员来说，尽可能多地保留该决策制定过程可能是至关重要的。

记录代码的部分问题归结为交付压力、不正确的设计以及记录事物如何工作的事实并不像开发它那样有趣或令人兴奋!许多工程师讨厌编写代码，但它是嵌入式工程师所做工作的重要组成部分，我们不能跳过它或三心二意地创建它。但是，在软件开发阶段可以牢记一些技巧，以确保未来的开发人员保持他们的发际线。

技巧 1 – 随手记录而不是事后记录

交付产品的压力通常会导致狂野风格的编码，其中代码到处乱扔，只是为了让某些东西正常工作，以便可以将其推出门外，在疯狂的编码过程中，很少考虑写下代码实际在做什么。产品交付后，设计团队会在“文档”阶段回顾代码。这样做的问题是，在编写代码之后可能需要数周甚至数月!对于一些工程师来说，记住他们昨天早餐吃了什么可能是一个挑战，更不用说两周前的一段代码做了什么了。结果是不准确的文档，后来导致误解和错误。

诀窍当然是在做出决定时随时记录。带有外部文档的正式流程肯定会减慢开发人员的速度，但在代码库中添加注释确实不需要更多时间。开发人员可以做的第一件事是写几行注释说明代码将要做什么。如果对实现进行更改，嵌入式开发人员可以立即更新评论。无论如何，在编写代码时开发注释只能节省时间并提高清晰度，从而减少错误并加快交付速度。

技巧 2 – 自动生成文档

尽管非常详细地记录了代码，但始终需要生成任何人无需查看代码即可看到的外部文档。这通常会导致双重文档工作。值得庆幸的是，有一些工具可以读取代码注释，然后生成代码的接口和其他文档详细信息!让工程师不必重复做同样的工作!比如Doxygen。在开发人员编写代码时，他们会以特定方式格式化注释，并使用他们希望在外部文档中提供的详细信息。然后，他们可以运行 doxygen 并生成准确反映软件中评论的 html、rtf 或 pdf 文档。这样做的好处是，如果你使你的评论保持最新，那么外部文档也将如此!

技巧 3 – 写不明显的评论

当开发人员记录他们的代码时，这很棒，但当文档只不过是变量或函数名称的重复时，则非常烦人。评论应该是描述性的，并提供超出显而易见的额外细节!提供尽可能多的信息，并且不要忘记提及相关和相关的变量或函数。开发人员应该能够通过阅读评论来了解软件的行为方式。从下图可以看到一个示例，其中记录了一个简单的映射数组。

技巧 4 – 提供示例用法以提高清晰度

当函数或变量注释包含如何使用它们的示例时，它会非常有用。说它应该如何使用是一回事，但更应该清楚地展示它是如何使用的。除了减少对象被错误使用的机会外，这还可以提供更清晰的画面。下图显示了如何记录函数的示例，向嵌入式开发人员展示应该如何使用它以消除猜测工作并给出清晰的画面。

技巧 5 – 创建文档标准

就像编写代码一样，应该有一个与代码注释和文档开发相关的标准，由于文档标准中的项目几乎没有那么多，因此强烈建议将其汇总到编码标准中，这是为了确保团队中的每个人都以相同的方式评论和记录，以确保易于开发，开发人员应该专注于手头的问题，而不是试图浏览评论。

技巧 6 – 使用文档模板

确保注释遵循标准的最简单方法是为标题、源和支持文档创建模板。创建新模块时，它是从模板创建的，然后添加相关信息，这将有助于确保文件信息块、代码段、函数和变量都以相同的格式注释，这种方法最好的部分是它还节省了大量时间，并且可以帮助减少将一个模块复制为另一个模块的假冒模板时的复制和粘贴错误。

技巧 7 – 从图表中拉/推

在项目的软件实施阶段开始之前，应该有一个软件设计阶段。这个设计阶段无疑产生了许多漂亮的图表，例如在实际实现过程中使用的流程图和状态机。虽然这些文档充当了软件的路线图，但在开发和测试过程中总是存在偏差!不幸的是，这些变化很少会回到图表中，结果是设计文档和软件不匹配!在实施和测试阶段，嵌入式开发人员可以将这些图表放在手边，以便如果出现偏差，可以在现场更新图表，让它们稍后更新永远不是正确的答案。毕竟，我们总是有最好的打算回去更新或修复某些东西，但从来没有时间去做。

技巧 8 – 一致地使用注释括号

听起来很奇怪，许多开发人员已经为何时、何地以及应该使用何种类型的注释括号而进行了战斗!这一切都归结为一致性。如果一个团队决定只使用 /* ... */ 样式的评论，那么就只使用那个样式。如果 // 样式已确定，则使用该样式。无论偏好如何，请确保每次都以相同的方式完成，这将有助于让生活更轻松一点。

技巧 9 – 保持可读性(即格式良好)

保持代码结构化和易于阅读非常重要，以确保误解和错误不会进入代码。评论也不例外。零星结构的评论使眼睛很难捕捉到评论，更重要的是很难捕捉到不合适的东西。注释的格式应该是这样的，如果代码被打印出来，注释不会跨多个页面运行。如果你使用块指示符，则在文件头或函数注释等大块注释中，不要包含任何尾随字符，例如 # 或 *，这只会使更新文档更加困难。

技巧 10 – 嵌入图像和图表

通过使用自动化工具，嵌入式开发人员可以在构建的文档中包含编码标准、缩写、项目详细信息、要求和大量其他项目，甚至可以包括流程图等设计图!利用这种类型的功能，代码库不仅可以包含已执行的代码和逻辑，还可以在一个地方包含你可能想了解的有关项目的任何内容!