10 tips for commenting C code
Source code that is well documented can decrease design cost and time to market by providing the insights into the software that would otherwise require time and experimentation to jog the developers’ memory on what and why of the code's behavior. These insights, if lost, can also increase costs and delay time to market by introducing bugs into the code base.
During the hustle and bustle of the development cycle it isn’t uncommon for commenting the C code to fall to the bottom of the priority list. With the pressure to get the product out the door, discipline usually fails and short cuts result in a poorly commented code base. Here are 10 simple tips that can be followed to help ensure that not only does the software get documented, it is also documented with useful information.
1 – Explain the why, NOT the how
There seems to be a human tendency when developing software to want to explain what a line of code is doing rather than why the code is there in the first place. A favorite example is bit shifting a literal x bits. The code and the comment generally looks something like
- // Shift bit by 8 and store in PortB
*Gpio_PortB |= (1UL<<8);
The comment itself leaves quite a bit to be desired. Anyone with a basic understanding of the C language knows by observation what the line of code is doing but why are we shifting by 8? Why are we storing the shifted bit pattern into PortB? A developer who reads this line of code six months or a year after writing it will have little idea without investigation as to what this line is really doing.
Something more appropriate might look something like the following:
- // Port B bit 8 controls the motor relay that needs to be turned off during the
// emergency stop procedure. Setting bit 8 high will disengage the motor through a relay.
*Gpio_PortB |= (1UL<<8);
This comment may not be perfect but it explains why the developer is shifting and bitwise ORing into PortB. Which comment would be preferred?
2 – Comment before coding
The general wisdom of commenting code has always suggested that comments be written at the same time as the code is. This insight makes a lot of sense; while the software is being written the why of it is fresh in the mind of the developer. The developer could wait until after the software is written but the pressure of getting to market and other priorities often make it highly unlikely that the comments will convey the original meaning.
An alternative to writing comments during or after the code is to instead write the comments before the software is written. This has the unique advantage of allowing the developer to think through what they are about to code and the why before ever writing a single line of code. It can be thought of as a translation of the software architecture and design phase of development into source. This approach keeps the software design at the forefront of the developer's mind and allows them to think clearly about what it is they are about to write code for.
3 – Use Doxygen tags
There are many different free tools available on the web that can translate code comments into useful document formats. A tool that can scan the source and generate html, rtf, and/or pdf should be a developer's dream. Why? Many development teams are forced to not only maintain their source code but also a wide variety of design documents that describe what the code is actually doing. These documents often trail what is actually happening in the program.
Using a tool such as Doxygen can translate the code comments into a document that fits the bill of these design documents automatically. The end result is that the developer now only has a single source and documentation chain to maintain, which should decrease the amount of time they need to spend creating “pretty” documents. (Also hopefully insuring that the documentation and source code stay in synchronization with each other).
Doxygen has become widely accepted, to the point that compiler and silicon vendors include Doxygen tags in their automatically-generated code. They are building Doxygen into the tool chains in order to make it easier for developers to generate documentation. As developers, shouldn’t we accept this free tool that makes documentation so much easier?
4 – Adopt a code style guide
A coding style guide contains all of the information a developer would need to properly create identifiers as well as on how the software should be documented. A style guide is useful to help provide the developer or a team of developers with the means to develop software in a uniform manner. This uniformity aids the developer by removing distractions from the software that may exist due to stylistic differences. The result is that code reviews are easier because the style of the code is uniform and the review can focus on actual code rather than superficial details of comment locations.
5 – Use a file header
Using a version control system is a highly recommended practice, but it can become tedious to always refer to the revision control system on the changes that occur in a code base. It can sometimes be confusing or unclear what a particular module's purpose is. Using these reasons as a basis, it is recommended that header and source files contain a comment header describing the function and purpose of the module.
There are a number of pieces of information that could be included in the header, but at a minimum it should include:
- File name
Module version number
Compiler version used to compile the code
The intended target
More tips on the next page...