Programmers are not unlike Dory from “Finding Nemo”, in that we have a limited memory. It seems like every time we sit down to code, and we are randomly struck by a lightning bolt of inspiration, we immediately lose it when we notice something shiny.
That’s an extreme example, sure, but programmers do have a problem of forgetfulness. It’s the nature of the job – we have so many tasks to perform and so many paths to track that we can’t possibly hold on to all our thoughts.
Thank God for comments.
Level 0 Comments: In-line
This practice, so common to college-age programmers, is often lost quickly in the “real world”. However, these comments are perhaps the most useful comments we can have.
After all, which is faster: tracing all the calls and variables in a block of code, or reading a short sentence describing the intended function?
While I generally recommend you not write useless comments (“This printf() function prints a line of text”), there are several key things you can do:
- Outline your code BEFORE you start writing, then use that outline to walk your way back through it later
- Explain why you chose one function over another
- Describe the operation of a library-based function, so you don’t have to keep looking it up
- Leave TODO markers in your code (vi will highlight these specifically, so they’re easy to find again)
- Comment out a “bad” line, so that you can see what it did before the fix
- Leave some tag that’s easy to search for later (like TODO, only without the convenient highlighting)
All of these comments improve readability by restoring some of the mindset you had when you were writing the code in the first place.
Level 1 Comments: Flowerboxes
Less common, but equally important, are flowerbox comments. These comments allow the author of a piece of code to relay more detailed information in a compact, highly-visible format.
There are a number of uses for flowerboxes:
- Doxygen comments – these not only generate HTML documentation, but they also describe a function’s purpose, arguments, and return types inside of the code itself
- I cannot recommend Doxygen-style commentary enough
- Seriously, if you haven’t looked into it before, LOOK IT UP
- Flow descriptions – these comments describe a higher-level flow for a function or program, allowing the programmer to quickly get a deeper sense of how the program is supposed to work
- Disclaimers and Formalities – Want the world to know who designed the code, and what it’s for? Flowerboxes at the top of the page get it done
- Detail an event or conversation relevant to the code – Maybe an offhand quote from a fellow programmer inspired the design of the next segment of code. Recording that information helps future programmers understand not just what the code is doing, but why you chose to do it that way
Level 2 Comments: Logs
Some of my more recent work contains fewer comments than I usually employ. This is because, instead of using inline commentary to describe an event, I print out a string detailing what is supposed to come next.
These are still basically comments, because they serve the purpose of a comment while providing information during runtime. It’s a win-win.
Level 3 Comments: Code Segments
Sometimes (usually) we decide to replace whole sections of code with new code. However, when we do a delete-and-replace, we run the risk of damaging functionality with no way to roll back the source.
Using flowerboxes or #if statements, we can make sure that the old code is safely kept away from the final product while allowing us to restore that functionality if the time comes.
Also, it’s interesting to see how the code has evolved over time.
Level 4 Comments: Extra Documentation
Strictly speaking, everything that happens during the development of a piece of code should be documented. All conversations, whiteboard diagrams, emails, flowcharts, and other documents should be retained, if only so you can see what decisions were made.