Commenting Code Effectively: The How AND The Why

Posted by:

Commenting Code Effectively: The How AND The Why

One of the most important skills a developer must have is the ability to comment their code effectively.  Over the years I have heard horror stories about companies acquiring other companies or developers taking over projects that other developers started were the code is trashed and they start over. 

Alternatively, hundred of hours are spent attempting to document the existing code base.  The problem with both of these approaches is that you can never capture the reason why things were done a certain way – you only can document how the existing code works.  When this happens, you often ask yourself “why was it done that way in the first place?”

When you write code, a large amount of time is spent trying to figure out how to make it work.  The code itself is just the end result.  Much like a math teacher asks you to show your work so that they can see how you arrived at the answer, a developer must comment their code as they are writing it to document (1) how the code works, and (2) why it was written that way.  The developers thoughts and decisions are just as important in the comments as an explanation of how the code works.  While a good developer can read uncommented code and eventually determine how it works, good comments can save hundreds of hours of work because they provide not only information about how the code works, but more importantly the reason why it was written that way.  Effective commenting makes code easier to maintain because developers can make informed decisions and spend more time fixing or enhancing the code rather than trying to figure out what another developer did.

Commenting code effectively can only be learned through practice and experience.  The true test of effective commenting is to lock the code away for several months, then come back to it, read the comments, and within a couple of minutes be able to understand what the code does and why it was written that way.  Alternatively, you can ask another developer to look at your code and comments and intepret it (peer review is always a good idea), but be cautious because another developer’s opinion can be biased, especially if that developer is working on the same code base at the same time.

My advice to all developers: Make sure all methods and parameters are documented, explaining what is the purpose of each method and what are the expected parameters and results.  This allows developers to make informed decisions when determining how to correct defects, make enhancements, or refactor code.  Add comments that explain the reasons why you wrote the code a certain way, especially if you spend time researching how to do something, or if you decided to do something a certain way for a certain reason.  If possible, provide examples for complex methods, or things that you feel other developers may not understand what you are doing at first glance.  If you know a section of code, if changed, will adversely affect something else, then document that as well.  When fixing code, put your initials along with a date/time and an explanation of what was changed and why you changed it. 

Finally, when you go back to the code that either you or someone else has written and you read the comments, update them if you find yourself spending additional time trying to figure out what the code is doing.  Over time, you will learn what types of comments are helpful to you, your development team, and future developers, and you will save yourself and other developers hundreds of hours of work.


About the Author

If music be the food of love, play on. I'm passionate about technology, music, food and family. Technology, because it's a part of everything; music, because there is nothing like a perfect harmony; food, because I love to eat (and sip wine); and family, because life has no meaning without it. I'm a software and technology geek who works with an amazing group of people, plays the piano, loves to cook, and has an amazing wife and daughter with a son on the way.

Add a Comment