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

There are few things more challenging in software development than acquiring a code base with little to no 文件资料 and being required to maintain it.  Documentation doesn’不仅要告诉工程师特定功能或变量的作用,而且还要演示并传达为何以特定方式实施软件。构造软件时会做出数百万个决策,这对于维护工程师乃至将来您保留尽可能多的决策过程都至关重要。

记录代码的部分问题归结为交付压力,设计不当以及记录某些事物如何工作的事实’和开发它一样有趣或令人兴奋!许多工程师(包括我自己)讨厌不得不编写代码,但这是嵌入式工程师所做工作的重要组成部分,我们可以’跳过它或半心半意地创建它。但是,在软件开发阶段应牢记一些技巧,以确保将来的开发人员保持发际线。

绝招#1–事后备案

运送产品的压力常常导致狂野西部风格的编码,在这里到处乱扔代码,只是为了使某些东西能够工作,以便可以将其推出门。在疯狂的编码过程中,很少考虑写下代码的实际作用或在显而易见的时间。产品交付后,设计团队将在“documentation” phase.  The problem with this is that it can be weeks or even months after the code was written!  It can be a challenge for some engineers to remember what they had for breakfast yesterday let alone what a piece of code from two weeks ago does.  The result is inaccurate 文件资料 that later leads to misunderstandings and bugs. (Let’s be honest, quite a few teams say they will go back and document it later when they have more time but “more time” never arrives!).

The trick of course is to document as you go while the decisions are being made.  A formalized process with external 文件资料 would definitely slow a developer down but adding comments into the code base really doesn’不要再花时间了。开发人员可以做的第一件事是对代码将要执行的操作写一些注释行,然后将其写掉。如果对实现进行了更改,则开发人员可以立即更新注释。无论如何,在编写代码时开发注释只能节省时间并提高清晰度,从而减少错误并加快交付速度。

绝招#2–自动生成文档

尽管对代码进行了详细记录,但始终需要生成任何人都可以看到的外部文档,而无需查看代码。这通常导致双重文档工作。值得庆幸的是,有一些工具可以读取代码注释,然后生成代码的界面和其他文档详细信息!节省工程师不必两次执行相同的工作!这种工具的一个免费示例是Doxygen。开发人员在编写代码时,会以特定的方式格式化其注释,并在外部文档中提供所需的详细信息。然后,他们可以运行doxygen并生成完全反映软件中注释的html,rtf或pdf文档。这样做的好处是,如果您保持评论最新,那么外部文档也将如此!在我的博客类别中的“设计周期”下,或者通过使用页脚中的搜索栏搜索Doxygen,可以找到有关如何启动和运行此工具的教程。

绝招3–写非显而易见的评论

It is fantastic when a developer documents their code but extremely annoying when the 文件资料 is nothing more than a repeat of a variable or function name.  评论s should be descriptive and provide additional details beyond the obvious!  Provide as much information as you can and don’不要忘记提及相关的变量或函数。开发人员应该能够仅通过阅读注释就可以了解软件的行为方式。在图1中可以看到一个示例,其中记录了一个简单的映射数组。

图1-映射数组

绝招#4–提供示例用法以提高清晰度

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

图2 –使用示例

绝招#5– Create a 文件资料 standard

Just like with writing code, there should be a standard that is associated with the development of comments and 文件资料 for the code.  Since there are not likely to be nearly as many items in a 文件资料 standard, it is highly recommended that it be rolled up into the coding standard.  This is meant to make sure that everyone 上 a team comments the same way and documents the same way in order to ensure ease of development.  A developer should be focused 上 the problem at hand not trying to wade through the comments.

绝招#6– Use a 文件资料 template

The easiest way to ensure that comments follow a standard is to create a template for header, source and supporting documents.  When a new module is created, it is created from the template and then relevant information is added.  This will help ensure that file info blocks, code segments, functions and variables are all commented in the same format.  The best part about this approach is that it also saves a ton of time and can help reduce copy and paste errors of copying 上e module to be the pretend template of another.  In order to make life easier, the author has developed templates that can be used to define header and source files that can be downloaded at //www.dbtgy.com/162-code-templates/.

绝招#7–从图中拉/推

在项目的软件实施阶段开始之前,应该已经有一个软件设计阶段。这个设计阶段无疑产生了许多漂亮的图表,例如流程图和状态机,它们在实际实现中使用。尽管这些文档是软件的发展蓝图,但在开发和测试过程中始终会有偏差!不幸的是,这些更改很少能回到图表中。结果是设计文档和软件没有’配对!在实施和测试阶段,请将这些图放在手边,这样,如果它们之间出现偏差,则可以在现场更新这些图。让它们以后再更新永远不是正确的答案。毕竟,我们始终最有意愿回去更新和修复某些东西,但是从来没有时间这样做。

绝招#8–一致使用注释括号

As strange as it sounds, many holy wars have been fought over when, where and what type of comment bracketing should be used!  In all seriousness though, no matter what your religion, it all boils down to consistency.  If a team has decided that 上ly the /* … */ style of comments will be used, then 上ly use that style.  If the // style has been decided, then use that.  Personally, the author prefers to use /* … */ for functions and module level declarations whereas // is used for function code 文件资料.  什么ever the preference, make sure that it is done the same way each time.  It will help make life just a little bit easier.

绝招#9–保持可读性(即格式正确)

Keeping code structured and easy to read is very important in order to ensure that misunderstandings and hence bugs do not find their way into the code.  评论s are no different.  Sporadically structured comments make it difficult for the eye to catch the comment and more importantly to catch something that is out of place.  评论s should be formatted such that if the code is printed out (pretty rare these days but I still occasionally print my code) the comments do not run across multiple pages.  In large block of comments such as a file header or function comment if you are using block indicators, do not include any trailing character such as # or *.  This will 上ly make updating the 文件资料 more difficult.

绝招#10–嵌入图像和图表

With the use of automated tools, it is possible to have coding standards, abbreviations, project details, requirements and a plethora of other items included in the built 文件资料.  The very design diagrams such as flowcharts can even be included!  Utilizing this type of capability allows for a code base to not 上ly contain the executed code and logic but also contain anything and everything you might want to know about a project all in 上e place!

5 thoughts 上 “记录嵌入式软件的10个技巧”

  1. Fantastic piece! I believe good 文件资料 is an embedded developers’ true legacy.
    什么’您对使用类似Wiki的页面来记录嵌入式项目有何看法?

    1. 我过去已经成功地成功使用了Wiki或类似Wiki的页面。一世’我一般认为’容易使他们与代码不同步。但是,它们可以是一个很好的资源。一世’ll经常生成pdf’Doxygen的s和html页面,然后将HTML发布到本地服务器,以便可见。谢谢你的问题!

      1. 我们进行了一项cron作业,只是从最新签入中生成doxygen html,然后将生成的html发布到机器的Web服务器上。
        我的意思是自动化。 --

  2. 你好

    向社区提出有关Doxygen的问题。
    (幸运的是)在考虑发布之前,要求编译器不发出警告越来越普遍。

    但是,你们当中有多少人使用Doxygen(或类似产品)启用了Doxygen生成的错误和警告检查功能,并且启用了在发布之前没有警告的标准?

    1. I’我有一个要求,可能是因为我刚读完本科两年,所以在代码发布中不应有任何警告。一世’自2009年以来,我一直在使用Doxygen’ve始终要求Doxygen也没有警告和错误。它’只是一种好的编程习惯! (尽管Doxygen中有警告,’并不像它那么重要’s in the code)

发表评论

您的电子邮件地址不会被公开。 必需的地方已做标记 *

该网站使用Akismet减少垃圾邮件。 了解如何处理您的评论数据.