图表的作用 - 专家分享：注释嵌入式软件的十大技巧

　　技巧7——图表的作用

　　在一个项目的软件实现阶段开始之前，应该有一个软件设计阶段。这个设计阶段无疑会生成许多漂亮的图（如流程图和状态机），并被用于实际实现。虽然这些文档作为软件的开发路线图，但在开发和测试过程中总会出现偏差！遗憾的是，这些变化很少会返回到图表中。结果是设计文档和软件的不匹配！在实现和测试阶段将这些图表放在手边，以便发生上述偏差时这些图表能及时得到更新。将这些图表留到日后更新永远不是正确的做法。虽然我们总是有返回去更新或修复的良好愿望，但这永远不是合适的时机。

　　技巧8——保持注释框使用的一致性

　　就像听起来一样奇怪，许多网络争论的内容是何时、哪里使用何种类型的注释框！不过严肃地讲，不管你的信仰是什么，归根到底是一致性问题。如果一个团队决定只使用/*…*/类型的注释，那么就只使用这种类型。如果决定使用//类型，那就只使用//类型。作者个人的观点是倾向于使用/*…*/进行函数和模块级说明，使用//进行函数代码说明。不管选择是什么，确保每次都按同样的方式去做，这样有助于生活更加轻松。

　　技巧9——使注释更容易阅读（即格式的美化）

　　为了确保避免误解并由此产生代码缺陷，使代码保持结构化和容易阅读很重要。注释也一样。偶尔结构化的注释会使眼睛很难捕捉注释，更难捕捉不在合适位置的内容。应该对注释进行格式化处理，这样如果代码打印出来时（虽然现在不常打印，但我偶然仍会打印代码）注释就不会分到好几页上去。在大块注释（如文件头或函数注释）中，如果你使用块指示器，千万不要包含进任何拖尾字符（如#或*），要不只会使文档更新变得更加困难。

　　技巧10——嵌入图像和图表

　　借助自动化工具的使用，在注释文档中包含编码标准、缩写词、项目细节、要求和大量其它条款就成了可能。甚至能够包含诸如流程图等设计性图表！使用这类功能允许代码库不仅包含执行代码和逻辑，还包含你想要了解的项目所有内容，并且所有信息都放在同一个地方。