Can you have code comments and clean code ?
Comments have the programming world divided. There are those who argue that you don’t need comments, code should be self-explanatory and you shouldn’t need to add anything. In the other corner, there are those who like to add their fair share of code comments. I want to share some code comments best practices with you.
Table of Contents
The best code comment is the one you don’t need to write
Let’s start with the drawbacks. Code comments provide additional information. That information has to be kept accurate by convention. Often, when code changes, the comments must change as well, and while we should have tests that make sure the code does what it’s supposed to do, we don’t have anything to ensure our comments are accurate.
Comments you should not write
There are those comments that don’t provide any value and clutter the codebase.
- Useless comments
import java.time.LocalDateTime; // import the LocalDateTime class
This is a classical example of a useless comment. It doesn’t add anything, It’s just some more text you need to read.
- Comments that should actually be a code-change
// Returns the number of Employees who were hired after the date List<Employee> getEmployees(String date)
We don’t actually need this comment. Although it provides valuable information about the behavior of the function, that information can be easily stored in the function name. A much better function name would be:
List<Employee> getEmployeesHiredAfter(LocalDateTime date).
- Commented code.
You should not have commented code in a production app. If you want to keep the code around in case you need it later, then put it in separate git branch. The code should either be there or it should not! There is no middle ground.
The code explains how, the comments explain why
Code comments should disambiguate code. They are the place to explain the reason why one decision was made instead of another. The principle of least surprise says that code should follow expectations. For various reasons, this cannot always be achieved. Sometimes the frameworks we use don’t work as expected, sometimes the business rules force our hand.
For example:
List<Pages> pages = getWebsitePages(); // The homepage is statically defined so it will not be part of the response. // For reporting purposes we have to include that as well. pages.add(homepage);
We don’t live in an ideal world
In an ideal world, the comments should only be used to disambiguate code. However, you sometimes have to break this rule.
- License comments.
You know them, the ones that look like this:
/** ***** BEGIN LICENSE BLOCK ***** Copyright 2019 lanraccoon … ***** END LICENSE BLOCK ***** **/
For legal reasons, these comments have to be part of the source code. You will find them mostly in open source code, that needs to subscribe to some sort of licensing. There is not much to add here. You have to add them and that’s that.
- Todo comments
I want to start by saying the code is not the place to keep track of outstanding work. There are lots of options that can be used to keep track of what needs to be done. Trello, Jira and github issues come to mind as great tools to keep track of outstanding work.
If you have to add a TODO comment, you should have a matching issue in your favorite issue tracking tool. You can then reference the issue in your comment.
int randomNumber = 4; // TODO #123 Generate a random number
Now whoever starts working on #123 can do search and get a head start on the dev work.
Let me know if you think of any other best practices about code comments ?