Always think twice before writing a comment. Is there a better way? Can you express yourself in code? Unfortunately, comments are one of the main sources of clutter in our files. If you find yourself commenting a complex and badly written piece of code, stop. Make better use of your time and clean up that code.

Most of the comments I see are completely redundant. Stop writing them. Seriously.

private Employee employee // The Employee instance
public Employee()  // Default constructor
private String name  // The name

Are these really necessary? What do they tell that you don’t already know? A lot of developers feel they are obligated to comment every variable or function. That is nonsense. Don’t make your code more cluttered than it needs to be.

Some comments are simply misleading. Maybe they didn’t follow up on code changes or have meaning only to the author.

// BEWARE!!! Logging to file can cause crashes in some cases.
void logEmployee() {
    printEmployeeToScreen();
}

Obviously, this function does not do file logging. At some point in time, maybe it did, but the developer who changed the function forgot to remove the comment.

With the introduction of version control systems certain types of comments became obsolete. Journal comments, which present a log of changes at the start of each file, are outdated. Instead of attributions and bylines, as shown in the following example, commits provide all necessary information.

// Added by Marko

Furthermore, because we can always revert to a previous code state, it is safe to delete commented-out code.

One other type of commenting that was commonly used in the good ol’ days were position markers:

/////////////// FUNCTIONS ///////////////

The problem with these is that if we use them constantly, they lose their meaning and fall into background noise, so we’re better off without them.

Oh, and you should also avoid too large comments and comments about system-wide information in local context and…

Ok, ok, I get it. Of course, not all comments are evil. Those that are informative, that explain the intent in a way that simply naming cannot, are always welcome. Strive to include comments that help clarify a decision.

void displaySpeed(int speed) {
	// received speed is in m/s, first convert to km/h by multiplying with 3.6
	int speedInKilometersPerHour = speed * 3.6;
	...
}

It can be really helpful to write warning and amplifying comments in certain cases. If you’re aware that a change to some seemingly unimportant piece of code can wreak havoc, note that to your fellow teammates or your future self. Of course, don’t forget to change that note once the code changes…

void resetBluetooth() {
	// Be sure to release the memory, it caused leaks
	delete lowEnergyController;
	lowEnergyController = nullptr;
	...
}

Make use of TODO comments in corresponding situations. It shows that you’re on top of the problem.

Maybe the most useful type of comments are those that automatically generate documentation. It would be unwise not to use that kind of possibility. And there are comments which you just have to include – legal ones. Copyright and authorship attributions are often put at the start of the files that use the code in question.

So, to comment or not to comment?. The key point is to make a connection between the comment and the code. If the comment introduces value, be it for you, your teammates or your clients, write it. Without that value, it is a burden that you’re better off without.

Stay tuned and happy coding.