Don't Comment Your Code - Rewrite It

Commenting is a topic I have have changed my mind about as I have matured as a software engineer. When I first started out I thought you should comment in every single nook and cranny of your code. These days I have swung the other way and for a good reason. I believe comments are a code smell and should be used sparingly. When I first started out I thought that comments would help me as a beginner to learn the code and get up to speed. I wanted comments because they were plain english road map to the pure greek I was trying to read. As I matured I realized it was just poorly written code that was really my pain point. Slogging through hundreds of lines in a single function, or variables named "x", "y", or 'i', those were my true pain points that made the code hard to read and hard to wrap your head around.

When should you comment?

In general I don't say never, because in computer science we so rarely deal with absolutes only trade offs. So I think using a comment is a definitive trade off situation. You need to be sure of the reason you are using it. I use them like they are warning signs warning the programmer of some dangerous craggy part of the code that is not obvious right off the bat what it's doing. Couldn't that be said of any code that is significantly complex, and highly coupled? Yes, it can! So I use comments frequently in legacy code that is not actively being developed. Since the business concerns do not always allow me to refactor the code as I would like to, and sometimes its just better not to shave that yak. So in those instances I use comments. I consider that a necessary evil.

Why are comments such an evil thing?

The short answer is they often lie to us. They tell you what the code is doing and can often be stagnate by several generation of that code. For instances if I said a function returns a string and it gets changed to returning an integer, because thats what it should do in the first place, and a developer makes the quick fix forgets to update the comment, and they usually do. Then we end up with a situation where the comment is saying it should do one thing and the code tells you it does another.

We know the truth to be the code. Since that's usually what is in production and is working at the time, or has been working for some time. So why read a comment that could potentially lie to you and waste you time when you could just read the code and see what its doing for yourself.

{% blockquote %}
"Code never lies, comments sometimes do.” - Ron Jeffries
{% endblockquote %}

How do we avoid comments?

On projects that are actively developed, I try to write my code in a way that is expressive of what it's trying to do. It's probably where I spend a majority of my time. I agonize over the choices and trade offs of names. I usually will just pick a name I think works for what the function or class does at the time and revise it later if I need to.

class Dog
	def bark
		puts "woof"
	end
end

The above code is an example of very expressive code. Even a small child would be able to understand what a dog is and that it has the ability to bark. In most cases the above code sample is far more simple than the code you will be writing but the principal holds true. Try to name things like you would need to explain it to a small child later. In this instance we can describe it like this "The dog can bark". It could just as easily be "the user can login", or "the user can edit their profile".

{% blockquote %}
“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.” – Martin Golding
{% endblockquote %}

I always thought the above quote was pretty funny, yet it really spoke to the pain I had experienced when slogging through hundreds of lines of terrible code. I really wanted to punch the author for making the job of maintenance so painful. A simple modification which should take 20 minutes in well factored code might take 4 hours in a steaming pile of legacy code.

Put thought into the names your give variables, functions and classes

During development it's not uncommon the first name I pick for a function or variable, will change several times during the course of project. Especially if the development cycle last more than one day. Once I have time to think on the choices and think up better choices for name, I will go back and revise the original code. Anytime I feel like a comment might be nice here. I take a step back and look at the code and even consult with a peer to see if it makes sense. Sometimes the answer is yes, but in general unless you are doing something very peculiar with the code, you shouldn't need a comment.

{% blockquote %}
“Any fool can write code that a computer can understand. Good programmers write code that humans can understand. ” - Martin Fowler
{% endblockquote %}

I take the above quote to heart, Mr. Fowler has encapsulated the reason for avoiding comments. Your code should be so readable that any human could understand it, and comments are in line documentation screaming out that a human cannot understand this with out documentation to go with it. This is why I avoid comments, and you should too! We comments are a crutch allowing us to accept bad code as long as it has a paragraph or a sentence to explain it.

Next time you write some code try to do it with out comments, look at your code and see how easy it reads. If it doesn't read easily and you cannot understand what you wrote with out a comment, don't comment your code rewrite it.