Thomas Sundberg

February 16, 2016

Comments are deodorant for your code

Filed under: Clean Code, Programming — Tags: , , — Thomas Sundberg @ 20:53

This post has been migrated to

Writing comments in a program is often considered a good habit. I hear people talking about code as “good and well commented”. This always makes me skeptic. What do people mean with “well commented”? It turns out, they often mean that every method has a lot of comments.

Why do you need a comment?

Reading code is an essential skill and something every developer does a lot more than they write code. Reading complicated code is easier if there are comments to guide you. But comments are sometimes used to describe the behaviour of bad code. If this is the reason why it is there, then it is just deodorant for the bad code. Something used to hide the bad smell.

This is a problem. Why was the code complicated from the beginning? There are many reasons to why something is complicated so answering that question is not easy.

An example

This is a piece of code that was written at the European Testing Conference in Bucharest 2016 during a workshop about Selenium.

public void buyCurrencyFirstAttempt() { // ... // Type 1 into the input field WebElement inputAmount = browser.findElement("amountField")); inputAmount.sendKeys("1"); // ... }

The participants that wrote the code wrote pseudo code that later was transformed into the real implementation. The comment above, “// Type 1 into the input field” would most likely have been removed if we had had more time.

But it happens that I see code like this. It also happens that it is considered good, well commented code. I don’t agree that it is good code. I think it is bad code that could have been improved. Comments should not be used. Instead refactor the commented part into a method with a name that makes it obvious what the it does.

The method then looks like this:

public void buyCurrencySecondAttempt() { // ... typeOneIntoTheInputField(); // ... }

This is, in my opinion, much better. It is not great or perfect. But better.

Notice that I made it easy for me and just turned the comment into the method name. The name could definitely improve, but extracting something and calling it the same as the comment is a step in the right direction. Improving the name is not easy though and it may take you some time before you come up with the perfect name. Until then, live with the imperfect name. It is better than the comment.

The extracted code looks like this:

private void typeOneIntoTheInputField() { WebElement inputAmount = browser.findElement("amountField")); inputAmount.sendKeys("1"); }

What should you extract?

A guideline you can use is to extract the block of code the comment cover. Start with calling the new method the same thing as the comment. Then see if you can come up with a better name.

A goal is to have the same abstraction level in the method you are working with. If all parts are at the same abstraction level, then it is much easier to read and understand.

Remember, a large method can always be refactored to a method where the details are at a higher abstraction level. This transforms it into a smaller method that is easier to read, understand and maintain.


I would like to thank Malin Ekholm for proof reading.



  1. Reblogged this on @rmate The Tester.

    Comment by armatearjun — February 17, 2016 @ 08:20

  2. It’s great to see another article coming out of the ETC2016 in Bucharest!
    One note: you should probably replace the following line of example code:
    WebElement inputAmount = browser.findElement(“amount inputAmount.sendKeys(“1”);

    WebElement inputAmount = browser.findElement(“amount”));

    Otherwise, it doesn’t really make sense.

    Comment by Alin Pandichi (@alinpandichi) — February 17, 2016 @ 09:13

RSS feed for comments on this post. TrackBack URI

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s

Create a free website or blog at

%d bloggers like this: