Training

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.