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.
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.
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");
}
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.
RSS