When I first started out in software development, I used to write a lot of comments in my code. To stay consistent with the developers who had previously worked on the same code, I even added to the historical comments above each module.
As a result, the top of a VB module could look like this:
' **************************************** ' Module: EmailProcessor ' Purpose: Process Email ' Author: John Doe ' Last Modified By: Jane Smith ' ***************************************** Sub ProcessEmail ' process email here Call ProcessEmail() End Sub
Over time, I’ve learned that comments should be used sparingly, and well-written code should reveal its intentions without requiring any comments. Jeff Atwood’s blog post from 2008 covers this:
http://www.codinghorror.com/blog/2008/07/coding-without-comments.html
“While comments are neither inherently good or bad, they are frequently used as a crutch. You should always write your code as if comments didn’t exist. This forces you to write your code in the simplest, plainest, most self-documenting way you can humanly come up with.”
An exception to the “no comment” rule is when you have code that needs some explanation even after you’ve simplified the code as best as possible. Another exception is the dreaded “TODO” comment and the technical debt that it causes.
Sure, you should commit working code into your source control system and remove dead code. But what about adding reminders in your code?
If some code needs to be written, you can either:
(a) write it now if it needs to go in immediately
or
(b) write it later if it should be deferred
In reality, it’s not uncommon to find “TODO” comments sprinkled throughout application code, maybe even more so in legacy code. Many developers even follow a convention to prefix their TODO comments with a particular syntax.
//TODO: don't forget to fix this code
Visual Studio even has a built in Task List viewer that can be filtered by “comments” so that you can quickly identify all your TODO comments.
http://msdn.microsoft.com/en-us/library/txtwdysk.aspx
Simply click View –> Task List from the menubar, then filter the results by “Comments”.
In fact, this feature has been around for several versions of Visual Studio.
http://msdn.microsoft.com/en-us/library/zce12xx2(v=vs.80).aspx
Comments like these tend to accumulate over time, and become a part of your Technical Debt. In order to prevent this from happening, you should consider using the Tasks List to identify these TODO comments during code reviews. This will help you clean up your code periodically and keep it clean.
For more information on Clean Code, I would highly recommend Robert C. Martin’s classic “Clean Code” book. It focuses on Java developers, but is also useful for C# developers.
http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882
The book looks great. I love recommendations like this!
I have mixed feelings about comments. When I do tutorials, I comment like a mad man. Same thing on quick projects.
As long as comments aren’t obvious, then I have no problem with them. The problem I see a lot of devs run into, especially senior level, is that they never comment and just assume that the code says what should be understood.
The problem with that, however, comes into play when a new engineer has to dive into the code, and the one who initially wrote it is long gone. Who do I ask? What was their initial intention?
Even worse is when they use one letter, or ambiguously named variables. Agggh!
There’s no excuse to use cryptic variable names these days. Instead, new code should have descriptive variable names, and methods should have low cyclomatic complexity.
When working with legacy code, consider refactoring blocks of code that you touch. Or at least, include a brief comment to explain the code if necessary.