Considerate Code Commenting

The way in which you comment the code you write can significantly impact other developers negatively or positively.  It is important to be cognizant of why we are writing comments (or not writing them).


Potential Negative Side Effects of Commenting

Misleading your reader – Some comments are misleading in nature.  What the author writes at the time might not make any sense to someone else besides the person who developed the code.  Or, even worse, it could steer them in the wrong direction.

May become inaccurate over time – Often times the same code is modified various times by multiple people.  This creates a risk that someone may forget to update the comment correlating to the code’s behavior.

Redundancy – There are many examples of code that is perfectly self explanatory accompanied by a comment telling the developer what they already know.

When Not to Use Comments

When the code speaks for itself – Ideally, you’d like for the code to be readable enough to not need explanatory comments.  This starts with establishing good naming convention techniques.  Keep in mind that someone else will most likely read your code at some point.  The architecture of your code in addition to the way you name variables, methods, classes, etc. should tell a story without another developer needing a user manual to decipher what the code is doing.

To establish a change log/journal – Other developers will most likely modify your code base and vice versa.  Sometimes you’ll see that someone decided to leave comments to log that they’ve made a modification.  When those changes are made they should be tracked in a version control system accessible by all contributing developers.  This alleviates the need for ever using comments as a change log or journal.

Closing braces – Others find themselves using comments at the end of the closing bracket of an ‘if statement’, loop, method, etc. to mark the end of a code block.  This is a strong sign that your block of code should be refactored concisely and in an easily readable manner.

To comment out code – Remember when I mentioned using a version control system to track changes?  That also means you should never need to comment out code on the off-chance that you’ll need it later.  BOOM!  Two birds with one stone.

When to Use Comments


When explaining implications – It is often a good idea to explain code execution implications via commenting which aren’t otherwise obvious to the reader of the code.  An example comment of this nature could be, “The method below should execute for approximately 10 minutes before a value is returned.”

When elaborating on a technical decision – Comments can be useful when detailing an architectural decision that was made for non-obvious reasons.

If the code isn’t clear enough – Unfortunately, there are definitely times when the code readability doesn’t fully allow the reader to understand exactly what the code is doing.  In cases like this it is wise to include an explanatory comment.

For legal disclaimers – Sometimes it’s necessary to include disclaimers in our code for legal purposes.  Try to refer to external documentation instead of including a bunch of legal content in your comments and bloating your files.

TODO comments – There are times when developers write comments to describe future action/approaches to be taken on a piece of logic.  This is especially common in the initial stages of an application when proper task tracking hasn’t been established, yet.

Auto-generated documentation – Many times there are commenting capabilities for automated documentation generation (XML commenting, JavaDoc comments, etc.).  This is a nice feature to utilize if you’re writing modules for other developers to consume (public APIs, etc.).

Hopefully this was useful to help you understand common commenting practices and to identify when they are beneficial or unnecessary.  Unfortunately, even though technology has come a long way and information is all around us, bad habits die hard.  The first step to recovery is admitting you have a problem!


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s