menu

Programming without comments

Posted Jul 25, 2015 by Mathieu Chiasson


Comments in your code should be avoided at all cost. Why? Because they waste your valuable time and your collaborators time. Good code does not need comments. You may have heard this before, if you did, unfortunately I'm repeating it.

What's good code and why doesn't it need comments?

Good code is code which follows a common easy to follow logic, consistent naming and indentation. Consider the following code:

if (orange == apple) {
    print("You are holding a square");
} else {
    print("You are holding a rectangle");
}

With some thinking you may have figured what we're comparing here but even if you did can you really figure what's an apple and what's an orange? In this example you would need comments to tell the next programmer what you're talking about. Here's the same code but written by a smarter programmer...

if (shapeWidth == shapeHeight) {
    print("You are holding a square");
} else {
    print("You are holding a rectangle");
}

Now doesn't it make a lot more sense? This is a very simple example but it serves as a very good example. When you choose descriptive names for your variables and functions the code becomes self documented. No need to spend time commenting everything. It just makes sense.

There are time when commenting is necessary, for example when you're attempting a complex logic which is not common. Try to avoid complex if you can. Often when you feel you need to comment your code, you've made it too complicated.

Simplify.

Comments