• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar
  • Skip to footer

Microcontroller Tips

Microcontroller engineering resources, new microcontroller products and electronics engineering news

  • Products
    • 8-bit
    • 16-bit
    • 32-bit
    • 64-bit
  • Applications
    • 5G
    • Automotive
    • Connectivity
    • Consumer Electronics
    • EV Engineering
    • Industrial
    • IoT
    • Medical
    • Security
    • Telecommunications
    • Wearables
    • Wireless
  • Learn
    • eBooks / Tech Tips
    • EE Training Days
    • FAQs
    • Learning Center
    • Tech Toolboxes
    • Webinars/Digital Events
  • Resources
    • Design Guide Library
    • DesignFast
    • LEAP Awards
    • Podcasts
    • White Papers
  • Videos
    • EE Videos & Interviews
    • Teardown Videos
  • EE Forums
    • EDABoard.com
    • Electro-Tech-Online.com
  • Engineering Training Days
  • Advertise
  • Subscribe

Documenting code: use this when you just don’t know what to write

May 11, 2017 By Scott Thornton Leave a Comment

Documenting code is something most people dislike doing. By the time you are done with writing, debugging, testing, fixing and re-testing, you are so sick of it that you just don’t want to look at it anymore.

But most of us have already been on the other side of the code: a recipient of some confusing pile that makes no sense and is going to take hours to figure out, because the original coder did not document, or sometimes worse, they documented the code but only enough to tease you with the idea that you have something to go on…until you get started adding that revision your boss wanted. Now you find that you overestimated the thoroughness of comments, blowing up the estimate you gave the boss on how long it would take to get the revision added.

Don’t be that person that poked out inadequate documentation. Of course, the purpose of a specific program or piece of code will vary widely and will make a difference in what you document. Nevertheless, think about what could happen to the hardware running your code, later product updates/upgrades/migrations, and anything else in the meantime. It’s a well-known fact that there’s code that was originally intended to work for a few months that has ended up being used for decades. (Remember Y2K?)

Documentation will pose different needs for different types of projects, so read this with a grain of salt if it doesn’t seem to apply to your “Hello World” printf demo code.

Here’s a list of things to consider writing about for others or even the future you. (Could you really remember 15 years from now how you passed that variable with techniques that you thought at the time were “elegant”?) Put some vital information in the header file (or lacking a “header,” to put at the top, in a commented section.)

  1. What/How/Why/When/Who: It’s OK to be brief. Describe in general terms what the code is for. Name the product, the main program it’s meant to be called by, etc. Describe the general goal(s) of the code. Briefly, explain how it accomplishes those goals. If it makes sense, explain why it was written, when the last revision took place, and if you are really concerned about the code you can put your name in there as the author of the code. Be careful with the latter, especially if you are on Linked In and job hop a lot. You might get contacted by a desperate coder who’s been asked to revise your original program from 20 months ago. Better yet, just document your code as well as you can. Not everyone who comes after you will leave their name in the comment section. On the other hand, if you upload it to git, then your name is only associated with that particular version. Whether you include your name depends on the project and whether it’s some temp code you are writing to troubleshoot something, an obscure snippet of in-house start-up company code, or something you plan to get glory for in the open source community.
  2. Mention the development tools, toolchain and/or environment and the make and version of those tools that you used to create the code. This is just a nice thing to do for the person following you. Even list the OS you’re using for the tools, if applicable. (Non-native tools can operate differently than native tools. This is especially useful if there’s a subsequent update to the Windows version that hosted your original dev tools.) Some code might be easier to re-do from scratch than to fix. Other code may be so complex that only replicating your exact original environment for making changes, debugging, and testing the original code in situ will make it possible not to have to re-do the code from scratch. Fixing broken code is like being a detective; leave clues for the next person so they can at least start out with an idea of what the situation was before the code got killed.
  3. Mention the libraries you used, the versions, and where to get them if it’s not obvious. Third party libraries should be spelled out to the extent that if that third party disappears or gets bought by a competitor, the library and any subsequent versions can perhaps be found.
  4. With embedded code, mention the processor chip or version, and/or any hardware configuration settings that might affect how the compiler works. This may seem like overkill, but compilers don’t come from heaven; real teams of people create them. Complexities can arise that make it impossible to figure out what’s going on unless you have the original set-up that was used to create the code in the first place. Giving all the information so others can demonstrate that your code worked well in the first place might be all they need to crack a problem, even if they have to contact the compiler makers to get an old version.
  5. If you do anything special with the build, mention it. Leaving the subsequent user with the environmental variables as you had set them is a kindness. Even kinder yet is to provide a batch file (as long as it doesn’t get lost) so that others can quickly duplicate your build environment without agonizing over settings you may or may not have selected. Anyone coming behind you will be impressed at your attention to detail within the documentation. (If you are this detailed, then go ahead and put your name in there.) Not all coders have the same experience and knowledge as you have, so assume that they may need a pointer rather than making them research any unique requirements.
  6. If you know that some constants are most likely to change, perhaps with subsequent product models, place those together, document them and what they affect, and make them easy to find.
  7. Once the code is released, anyone who comes in to make changes should also document revisions in a similar manner.

Comments don’t add to execution time, so no one is hurt by writing too much (as long as it’s relevant). On the other hand, one could get annoyed with too many comments sprinkled in between each line of code to the point where you can’t see the flow of the source for all the comments. Therefore, if your project has an overabundance of documentation, rather than embed it all in the source code, you can create a separate readme.txt file. If a readme might get separated and lost, you can indicate to the reader that additional documentation is at the end of the file or provide a link to a web page. Repositories like git might be around for several decades (or not), so use your best judgment. Readme files are generally easier for adding revision documentation, however.

No code or its documentation will ever be bulletproof. The point is to make the best effort with a reasonable outlay of time and energy. Murphy’s law, however, states that if you have perfectly documented code, no one will ever need to use it. (However, the poorly documented code has a much greater chance of needing changes or to be ported to 3 other processor architectures while you still work at the company and know the guy who inherited your code.)

If you have ever had to recreate some set-up or change code and the documentation was done well, you might recall how grateful you were to the originating author(s). That author may never know your gratitude, but pay it forward with your own well-documented code. Someone will silently thank you some day, at which time good karma will shine on you. In the moment, you will think you are just lucky, but the documentation fairies reward the faithful.

 

 

 

Filed Under: FAQ, Featured, Industry Experts, Tools, Training Tagged With: basics, FAQ

Reader Interactions

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Primary Sidebar

Featured Contributions

Five challenges for developing next-generation ADAS and autonomous vehicles

Securing IoT devices against quantum computing risks

RISC-V implementation strategies for certification of safety-critical systems

What’s new with Matter: how Matter 1.4 is reshaping interoperability and energy management

Edge AI: Revolutionizing real-time data processing and automation

More Featured Contributions

EE TECH TOOLBOX

“ee
Tech Toolbox: 5G Technology
This Tech Toolbox covers the basics of 5G technology plus a story about how engineers designed and built a prototype DSL router mostly from old cellphone parts. Download this first 5G/wired/wireless communications Tech Toolbox to learn more!

EE Learning Center

EE Learning Center

EE ENGINEERING TRAINING DAYS

engineering
“bills
“microcontroller
EXPAND YOUR KNOWLEDGE AND STAY CONNECTED
Get the latest info on technologies, tools and strategies for EE professionals.

DesignFast

Design Fast Logo
Component Selection Made Simple.

Try it Today
design fast globle

Footer

Microcontroller Tips

EE World Online Network

  • 5G Technology World
  • EE World Online
  • Engineers Garage
  • Analog IC Tips
  • Battery Power Tips
  • Connector Tips
  • DesignFast
  • EDA Board Forums
  • Electro Tech Online Forums
  • EV Engineering
  • Power Electronic Tips
  • Sensor Tips
  • Test and Measurement Tips

Microcontroller Tips

  • Subscribe to our newsletter
  • Advertise with us
  • Contact us
  • About us

Copyright © 2025 · WTWH Media LLC and its licensors. All rights reserved.
The material on this site may not be reproduced, distributed, transmitted, cached or otherwise used, except with the prior written permission of WTWH Media.

Privacy Policy