Documentation Done Right: Why Firmware Teams Need Robust Documentation

Why is Documentation so Important?

When you are deep in the weeds working on a project, it’s easy to think “There’s no way I could ever forget how this code works!” We have all been there, and it always feels silly to have to admit you no longer know how your implementation works. Sure everyone has also had the thought “Who wrote this code?” Well, the elephant in the room with us is that these situations are all too common and totally avoidable! With just a little bit of time and effort, some additional documentation could have saved the day! Or at least saved you some time re-learning how your project works. But how should I go about documenting my work to make the best use of what little time I may have? 

Overview 

There are many different ways to add supporting documentation to a project. Inline comments, Doxygen function headers, architecture diagrams, etc. No single solution is the one thing guaranteed to make your project a success. Projects with great inline code comments but no usage guides are frustrating to update or modify. Alternatively, great system level docs will not offset poor or undocumented code. This isn’t to say you should be spending just as much time documenting as you do developing. Instead, try to incorporate a balanced approach documenting multiple aspects without overdoing it. This will save you time in the long run greatly improving ramp up times whenever someone new is introduced to a project. So what types of documentation should we add, and how much time should we spend in each area?  

Architecture Diagrams

While projects tend to grow and change over time, spending even just a day trying to flesh out how you imagine a project should work can help to spot potential problems and avoid costly refactor time. If your planning or architecture diagrams look like a mess, the implementation will likely also have its problems. If anything comes up down the road where you need to change something fundamental, spend some time updating your diagrams to ensure they reflect the most current state of things. This type of pre-planning will not just save you time on the implementation, but can also serve as a guide for how your project works to outside eyes down the road. 

Doxygen 

As you go about writing your code, it may be easy to lose track of everything that you have added. Forget trying to go back to an API document and updating it manually, that is painful duplicate work that may easily be avoided. Instead tools like Doxygen are able to take your typical header definition comment blocks and transform them into separate API documents automatically! Worst case, if this process is new to you, it will take an additional minute or two per function to save you hours of work down the road. If all your code has proper function headers, Doxygen can create a full API document for you in multiple formats like HTML or PDF. You can even incorporate this documentation step into your build scripts so that once it’s set up, you never have to worry about it again!

Inline Comments and Self Documenting Code

For any engineer, inline comments are the most obvious form of documentation, but also we have found they are often very overlooked. Instead of telling yourself “I will come back and comment this when I am done”, spend just a minute or two to ensure anyone will be able to understand your complex new algorithm. Just don’t overdo it! There’s no need for a comment above every single line, as that can cause a viewer to skip over important info because there is simply too much to read. Along with this, it is becoming increasingly standard to practice using Self Documenting Code, which is just a fancy way of saying to write your code with variable and function names that describe their purpose at a glance. While we all love a “for x in y” loop, try to get in the habit of saying “for someChar in outputString” and all of a sudden you may not even need additional comments. It’s the best of both worlds letting you get away with only needing additional notes on the more complicated stuff. 

Examples as Documentation

What is the benefit of perfectly documented code when you need to spend hours sifting through the code just to understand how all the pieces work together? A few simple example files can go a long way to show others how your system works. People often say a picture is like a thousand words, but an example file can truly be invaluable. While examples may be some of the more time consuming items to create, maybe think about how you can work them into some test framework. That way not only do you get regression testing as you go, but others will be able to see how they may use what you have written from your test code. 

Recap

Hopefully now you have a better understanding of why proper documentation is so important. 

If you have a backlog of underdocumented code and don’t know where to begin, feel free to give us a call! Our experts would be more than happy to guide you in the right direction, or to even lend a hand getting you up to speed.

Book a call with us to get the conversation started. 

Or, check out our CI build platform and increase your productivity.

We look forward to hearing from you! -D5