// This is the name of the header
private String headerName;

/**
 * Returns the name of the header
 * @return Header name as a String
 */
public String getHeaderName() {
  return headerName;
}

Have you ever seen comments like these?
Are you not grateful for it?
Don't you just wish you could find that individual and ... shake his or her hand?

Thank you for that insightful comment!
Without this comment I would never have figured out what we would store in this mysterious variable!
Three blessing upon thee!

Sarcasm and exaggerated example aside; at some point in most developers young life, you might have thought that writing long and descriptive comments for every method is a good thing.
After all, how would anyone besides yourself be able to understand what the code does? We would not want the other developers waste his or her time, trying to read the code.
Unfortunately, I did this too. Until learning what readable code really is all about.

Please allow me to elaborate further why it is my firm belief that the policy of writing comments is generally a bad thing, and why it should be avoided whenever possible.

Student goodStudent; // A good student writes comments

In school they teach you to comment your code. Comment classes. Comment methods. Comment variables. Comment everything.
Why do you believe that is so? Why do you learn at most schools to comment your code during your education? Some might say it is for the teachers benefit, in order for them to understand your code without having to read the code. Perhaps the teacher expects you to elaborate your programming choices.
A better reason to do so, would be to force you to spell out what you think the code does, so that the teacher may read it and see whether or not you understand the code.
Whatever the reason is, the result may be unfortunate because we never learn when not to comment. You are practically brainwashed to comment your code from the beginning of your developer journey.

I recall working with other students who told me that their teachers graded them based on their comments. Imagine dropping in grades because you forgot to write comments! How would you as a student know better, of course you would trust your teacher to teach you best coding practices.

Why is it that we are not learning how to write readable code? We learn how to read and write a programming language, sure. We learn the syntax, differences between modifiers, the range of scope, object oriented programming (OOP), and so on.
We do not, however, seem to be learning how to write readable code in such a way that comments are made redundant. At the very least, I would expect to be informed that there even is such a thing as readable code, and that comments should not be needed.

Not once did we sit down and talk about how the real professionals go about writing understandable and readable code, that does not have comments that simply state out what the code does.
Instead what we have is mediocre code with a bunch of comments explaining what it does.

Comments are the failure of writing readable code!

Cards tableCards; // Cards on the Table

Are comments useful?
Yes. Well, that depends. They certainly can be. There will always be times when you write code that you simply cannot refactor or rename in such a way that the reader would understand crucial information.
Does that mean we should do it? Most certainly not. It should be avoided like the plague. Comments rot, spread, and slowly infest the code base with noise and misleading information caused by developers either forgetting or neglecting to update the comments. Sometimes the comment is simply plain wrong, or badly written.

When should I use comments?
When you are unable to convey what is going on in the code itself.
When understanding the method required to you know essential context information.

Frankly I would rather spend 5 minutes trying to figure out a single good and descriptive method name, rather than taking the easy path of writing comment that explains what a method is doing; which more than likely simply lists out what a method does.

Should I comment a method when it can return more than one thing?
You might have read comments that state something similar to; "this method may return null", or "this method will return one item on X circumstance, but more in Y circumstance".

If your method does more than one thing, it probably should be split up into several smaller methods that each do one thing. Perhaps even into a class.

No developer should expect a method to return null. We can use Optional instead.

Long methods should have comments!
Yes, a long method would be difficult to read and understand without an informative comment.

However, what you might as well say is this;

  • The method is too long
  • The method is unreadable
  • I would rather just comment this instead of cleaning it up, or
  • I don't know how to clean this up

The latter is normal, everyone have at some point written code that is too complex and difficult to read and understand. Does that mean we should give up and write comments? Probably not.

What you as a developer should be doing, is to work towards improving yourself. Self-study. Practice code katas. Read books. Watch youtube videos about readable code, clean code, and practice test driven development (TDD).

You should make it a personal challenge to make that piece of code readable instead of adding a comment to it. Yes, it may cost 5 minutes. 30 minutes. Perhaps even an hour.

TDD is a good way to practice writing readable code. Your code would have to be written in such a way that it becomes testable, which usually has the side effect of being more readable with good naming and separation of concerns.

What about legacy systems?
Many of us have been there. Working with legacy code can suck. There is no denying it.
However there are always options for how you may keep adding/modifying legacy code without adding to the chaos. In fact, you may slowly be improving the code over time - making it more readable. Without adding more to the comments.

If you are working on a long method that would be very difficult to refactor and rename into smaller readable methods, I would probably want to see that at least the new code and new modifications are readable without needing to add comments.
I simply do not want, or need, to have duplicate information that simply echos what is happening in my code base.

Are there too many comments in my code?
If you are reading through code with a lot of comments between every variable and method, at some point you will stop reading them.
If not you, then another developer. Many developers have learned that comments lie. Comments trick you. Comments waste your time, because most of the time after reading a comment, you begin reading the code.
In the end, comments are just fluff invented decades ago to help coders understand very difficult code. In a time when comments were useful. Not only useful, but a necessity!

The consequence?

You will miss and ignore the important comments that are helpful!

LocalDateTime storyTime; // Several years ago

When I first begun working in my first real developer job, I did as any fresh student would do; I followed lessons that I had been thought at school.

I followed the new-dev routines and familiarized myself with the developer guidelines. I was introduced to new tech, Spring Boot - and begun learning and reading code.

When I started coding, doing the "real work", I made sure to comment all my code, following javadocs standard perfectly.
After a while I noticed that no one else was doing that, and figured that perhaps they were lazy, or didn't care enough whether or not people did write them.
Fair enough, I kept doing it because that is what I had been thought.
My comments and code was beautiful. Between each line you could see comments that in themselves formed a sort of symmetry. A flow. Predictability.

A few months passes, and I've gotten a few comments about my in-code-comments.

"Why did you comment this? I don't think you need to comment this, it it pretty obvious this returns a String!"

I agreed, but argued that by following javadocs formatting, we would get a very nicely readable documentation we can look at. We can even print it out and it would be wonderfully easy to see what everything is and does.

Sure, I was not wrong, but I was not right either.
I later came to realize is that no one (including myself) don't really care about javadocs, because there have never even been the need to look at it.
I just loved the idea of having it, because it was beautiful.

Beauty will blind you

After some time, I got more comments (the verbal kind). No one actually told me to stop writing comments, but I started to realize that no one really wanted comments. I would save myself a lot of trouble and time by simply not writing them.

"If they don't want comments, then I am not going to give them any!" - Old me

I stopped writing comments. I didn't remove the old comments I did, but I made sure not to write new ones!
Some time passes. I become more accustomed to having to read code without comments. I no longer have comments that are holding back information, nor do I have comments that are misleading, or comments that is lying to me.
No longer was there a man at the front door, telling me what is behind the door. I just enter, take a look, and then I'm out again.

During a code review, I discovered a method that I could not for the life of me figure out what it does. It had a method name perform and did many small things. The name of the class has the format xHandler. Sure, it handles x, but what does it do? It performs something! A dance perhaps?

"What does this method do? It's too long and complex to understand as-is, it needs a comment!" - Old me

The other developer agrees that is is difficult to understand, excusing himself explaining it took a long time to write and that he neglected to clean it up because he was tired working on it. Something I can fully understand.
The developer then performs the fix and sends it back to me.
I notice that the class name and method name had changed, but I did not see the comment I expected! #Reeeeee!
After I had finished fuming over the lack of a comment, I noticed other changes in the code. The method had become smaller somehow, and a few other methods had been added. There was even a new class with 2-3 methods.
I read the code again, and lo and behold, I could understand what the code did now. It only did one thing, it started x. It used the new class to perform the initial setup preparations, and then the class itself did the startup. So simple. I did not even have to read the innermost code to understand what is going to happen. It is written plain as day. Human readable text.
To be more specific: humanReadableText()

I told him the code looks very good, and I was no longer disappointed that he did not follow my advice to write comments. He instead made it better. He made it readable. No need for comments to begin with!

Why did I initially want comments added?

Because the code was difficult to read and understand!
Comments should not be a go-to solution to cover bad code. It is a absolute last resort.
Comments are spawned from inadequate code. Code that has room for improvements. Code that is begging to be refactored and renamed. Code that wants to read!

Writing readable code is the hardest there is!
There is no doubt about it. I can spend several minutes trying to pick my brain figuring out what to name this... thing. It is nothing to be ashamed of.
Once you become better at it, doing it more and more, you will notice when you get back into your old code that you can still follow it. You do not have to remember what you write, you can simply navigate it because it is written readable.

Commented distractions

Comments caused distractions away from what matters: the code.

Distractions...
  • caused by comments that tell half-truths of what a method does.
  • caused by having outdated comments.
  • caused by comments saying one thing, while the code saying another.
  • caused by lying comments written by a developer that thought the method did X, when it really did Y.

Continuing the story

At some point, we got a new consultant in our team. A swedish fellow. Very good at what he does.

After some time we slowly got introduced to a different way of writing code. Test Driven Development. Testable code. With methods that are short and concise.
A side effect of this was having more than the usual one or two long methods. Instead we have plenty of smaller methods that does exactly what the method name said it does.
If I were to jump into a random method, it might be a bit difficult to understand what it is used for, and where it goes.

However, from the top level it was very easy to follow along, understanding and reading the code.

Common arguments against multiple smaller methods are:

  • The code is difficult to follow
  • It's only 1-2 lines
  • Reading this method does not help me understand where it is used

To that I say: When you start reading a new book, you don't start in the middle of the book expecting to be able to understand what have happened beforehand!
You start at the beginning!

Summary summary; // A summary of things

There is a lot of bits and pieces to take from this. If I had to pick out the most important lessons I have personally gained most from, it would probably be this.

  • Comments should be avoided whenever possible.
That does not mean it should never be written. You should definitely write comments in the 1% scenarios when it would provide essential intel for the next developer. However the 1% cases is absolutely not an excuse for developers to comment most methods, as many does.
  • Practice writing readable code.
The greatest resource you have available to you, are your fellow developers. Be it young or old.
Don't hesitate to ask for eyes on the code you are writing. Can any of you think of a way to make it readable? If not, hang your heads in shame and write the comment; begging for forgiveness from all your readers.
  • When you have to write comments, make sure it explains "why", and not the "what"
Don't simply write out what a method does. In the very very few cases a comment would be appropriate, 99% of the time is should be the why.
  • Avoid writing monster methods.
Your code should tell the story. If a developer have to read complex math problems or algorithms to understand what a method does, you have code that probably should be split into readable methods or variables.
By the way, if you have a method with 3-4 input variables that are used throughout several methods; chances are that you got a hidden class that is waiting to be created.

Having trouble refactoring legacy code?

I would highly recommend the book Working Effectively with Legacy Code, by Michael Feathers.
It will provide you with easy-to-do strategies to help you work with "old code", while making sure that the new code you write is readable and understandable.
The sprout methods and classes are easily my most common strategies when working with older legacy code, and there are circumstances other methods may apply.

Please share your own experiences with good and bad comments in the "comments" below!