Comments are deodorant for your code

Filed under: Clean code, Programming, — Tags: Java, Refactoring, Selenium — Thomas Sundberg — 2016-02-16

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(By.id("amount"));
    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(By.id("amount"));
    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.

Acknowledgements

I would like to thank Malin Ekholm for proof reading.

References



(less...)

Pages

About
Events
Why

Categories

Agile
Automation
BDD
Clean code
Continuous delivery
Continuous deployment
Continuous integration
Cucumber
Culture
Design
DevOps
Executable specification
Git
Gradle
Guice
J2EE
JUnit
Java
Javascript
Kubernetes
Linux
Load testing
Maven
Mockito
New developers
Pair programming
PicoContainer
Presentation
Programming
Public speaking
Quality
React
Recruiting
Requirements
Scala
Selenium
Software craftsmanship
Software development
Spring
TDD
Teaching
Technical debt
Test automation
Tools
Web
Windows
eXtreme Programming

Authors

Thomas Sundberg
Adrian Bolboaca

Archives

Meta

rss RSS