There are few things more challenging in software development than acquiring a code base with little to no documentation and being required to maintain it.
Documentation doesn't just tell an engineer what a particular function or variable does but it also demonstrates and conveys why the software was implemented in a particular fashion. There are millions of decisions that are made when implementing software and it can be critical for the maintaining engineer or even the future you to retain as much of that decision making process as possible.
Part of the problem with documenting code boils down to delivery pressures, improper design and the fact that documenting how something works just isn't as fun or exciting as developing it!
Many engineers (including myself) hate having to document code but it is such an essential part of what embedded engineers do that we can't skip it or half-heartedly create it. However, there are some tricks that can be kept in mind during the software development stage that will ensure future developers maintain their hairline.
Trick 1 – Document as you go not afterwards
The pressure to ship a product often leads to wild-west style coding where code is flung here and there in an effort to just get something working so that it can be pushed out the door. During the frantic coding little thought is ever given to writing down what the code is actually doing. Once the product ships the design team goes back through the code in a “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 documentation that later leads to misunderstandings and bugs.
The trick of course is to document as you go while the decisions are being made. A formalized process with external documentation would definitely slow a developer down but adding comments into the code base really doesn't take any more time. The first thing the developer can do is write a few comment lines on what the code is going to do and then write away. If a change in implementation is made the developer can update the comment immediately. In any case, developing the comments as you code can only save time and increase clarity that results in fewer mistakes and quicker delivery.
Trick 2 – Automate the document generation
Despite documenting the code in great detail there is always a demand that external documentation be generated that anyone can see without looking at the code. This usually results in double documentation efforts. Thankfully, there are tools available that can read in code comments and then generate interface and other documentation details of the code! Saving the engineer from having to do the same job twice!
One free example of a tool like this is Doxygen. While a developer is writing their code, they format their comments in a specific way with details that they would want in external documentation. Then, they can run doxygen and generate either html, rtf or pdf documents that exactly reflect the comments within the software. The nice thing about this is that if you keep your comments up to date then the external documentation will be too!
To read more of this external content, go to “Write non-obvious comments.”