Java|嵌入式开发：记录嵌入式软件的10个技巧 MongoDB|数据库|飞利浦·斯塔克

文章图片

文章图片

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

【Java|嵌入式开发：记录嵌入式软件的10个技巧】记录代码的部分问题归结为交付压力、不正确的设计以及记录事物如何工作的事实并不像开发它那样有趣或令人兴奋!许多工程师讨厌编写代码，但它是嵌入式工程师所做工作的重要组成部分，我们不能跳过它或三心二意地创建它。但是，在软件开发阶段可以牢记一些技巧，以确保未来的开发人员保持他们的发际线。
技巧 1 – 随手记录而不是事后记录
交付产品的压力通常会导致狂野风格的编码，其中代码到处乱扔，只是为了让某些东西正常工作，以便可以将其推出门外，在疯狂的编码过程中，很少考虑写下代码实际在做什么。产品交付后，设计团队会在“文档”阶段回顾代码。这样做的问题是，在编写代码之后可能需要数周甚至数月!对于一些工程师来说，记住他们昨天早餐吃了什么可能是一个挑战，更不用说两周前的一段代码做了什么了。结果是不准确的文档，后来导致误解和错误。
诀窍当然是在做出决定时随时记录。带有外部文档的正式流程肯定会减慢开发人员的速度，但在代码库中添加注释确实不需要更多时间。开发人员可以做的第一件事是写几行注释说明代码将要做什么。如果对实现进行更改，嵌入式开发人员可以立即更新评论。无论如何，在编写代码时开发注释只能节省时间并提高清晰度，从而减少错误并加快交付速度。
技巧 2 – 自动生成文档
尽管非常详细地记录了代码，但始终需要生成任何人无需查看代码即可看到的外部文档。这通常会导致双重文档工作。值得庆幸的是，有一些工具可以读取代码注释，然后生成代码的接口和其他文档详细信息!让工程师不必重复做同样的工作!比如Doxygen 。在开发人员编写代码时，他们会以特定方式格式化注释，并使用他们希望在外部文档中提供的详细信息。然后，他们可以运行 doxygen 并生成准确反映软件中评论的 html、rtf 或 pdf 文档。这样做的好处是，如果你使你的评论保持最新，那么外部文档也将如此!

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

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