I have always believed that clean code is readable code, and if your code is readable, then it shouldn't require masses of comments to explain it. However, in the course I am being taught, we are being told that in programming, comments are massively important to help another developer understand your code and what it does. So what is the consensus of the dev community?

Do you feel comments are key, or redundant if your code is written well?

Comments are code too.
So if yopu write them, you have to maintain them.
Andf writing good comments is as hard as writing good code.

But yes, they are important for non-self-explanatory parts and spects of your code.
Their main task is to tell, why the actual code has been written.

Clean code should make obvious WHAT it does, but can't tell WHY it is doing so. Especially if these reasons are not located in that code, but somewhere else, such as other software, other systems, physical constraints. Or "see chapter X of document Y" style comments.

I personally comment more than that. Whenever I had to actually think about stuff, I put the gist of my thoughts as comment. That has helped me a lot to understand my own code later because if I had to think the first time, I also would have to think next time, and that would take more time than reading a comment.

Very often comments are redundant and code smell. I truly hate code that reads

const length = 20; // length in cm

There is no excuse not to write at least:

const length_in_cm = 20;

(You could drive this point further with a class that both stores value and unit and is able to switch between units.)

I really don't need comments to repeat code that has been written.

// define a number with 0
const number: int = 0;
// increase the number by one
number += 1;

That is just irritating. And it will grow apart:

// increase the number by one
number += 3;

Who is right? The comment or the code? Just delete the comment here!

Though while good code is a self-commenting as possible, code will never tell you WHY it's doing things. It explains the HOW and the WHAT. (Unit tests do not necessarily explain the WHY as well. They just define seemingly correct behavior.)

It's helpful to explain the counter-intuitive aspects to your colleagues to not force them to go through the same journey.

I add a comment only if I imagine myself reading that code first time and asking - whyyy?

So in the end of comment there should be an imaginary "that's why" :)

The *right* level of commenting is key - too many comments are often just as bad, or worse than not enough comments imho.

Commenting obvious code, boilerplate, or just repeating function names in comments are useless. You only need to comment if you've got something valuable that needs to be said. Sometimes that will simply be explaining the top level purpose of a class / function / whatever, and sometimes it will be on a more micro level, explaining why or what a particular line, or chunk of code does.

The former category should always be present in an ideal world - that's about keeping your code easy to navigate. If you find yourself adding too many of the latter category however, chances are you're either explaining things that don't need to be explained, or you should be refactoring your code so it's more readable.

Comments are for the cases where the code does something non-obvious for a reader who already knows the language.

Passing 0x2389a832e as parameter somewhere because the shaman in your lucid dream told you to and it's why the code works? Write a comment.

Writing a comment so you remember why the variable "abcd1234" exists? Consider not producing offspring.

Your teacher is wrong. Writing comments is sometimes necessary but should be done knowing that the comment is itself an act of giving up. I have to give up on writing code that is clean and easily understood because too much tech debt to tackle today etc. Comments are to be avoided. They are not 'good', they're smelly.

I think that regarding comments all has been said that needed to be said.

A word of general advice I repeat very often here: question everything.

Exactly thx. to such unspecific advice codebases exist where you are forced to delete the comments with sed or another tool.

Might sound radical, but as many people before have pointed out: Comments need maintenance.

Many devs here made the experience that a comment once lead them down the completely wrong path I guess, not only wasting time but going quite insane as the comment e.g. was the inverse of what the code was doing.

It would be a good example imho to teach at the moment of commenting how e.g. git blame / git history works:

Checking the history of the VCS and assuring that the date the comment was added and the last modification date is "in sync" is a good way of not only knowing wether the comment _should_ be relevant, but when and what has happened the last time the code was modified.

These lil extra step can give you a lot of insight regarding the codes actual state, the last modifications (in best case tickets to read upon)… Who was the last person working on it... And if the documentation is up to date.

Or utter outdated garbage that should be put to rest.

:)

Commenting is one part of "keeping history documented"… the VCS is it's counterpart.

They should be taught together imho.

If you use JSDoc/Documentation.js/ts-doc/... to auto-gen documentation (be it as part of a README.md or a static site) then no problem (as long as the types and names are in sync with the code).
However, as many people already said, comments can sometimes be useless (often an indication of unclean code) and outdated, and they are an extra thing to maintain.
Now, the "you shouldn't comment on your code" philosophy is also terrible (IMO) as you (or anyone else) may read the code some time later (days, weeks, months, ...) and only understand the What but not the Why.
Now, ADRs can come in handy to answer the "Why has this approach been used?" but they are a form of documentation as well (which has its own pros and cons) which may be less connected to a specific part of code.

Of course, what the code does and its complexity will change whether or not comments would really be useful or not.

@k0pernikus agree to all

I usually explain the reason why I'm doing something in a piece of code. Sure, i have some redundant comments for methods and parameters, but the one thing I always strive for is explaining why I did something. Sometimes I have to do dumb, ugly, or not immediately obvious solutions due to time constraints, buggy dependencies, and/or my own incompetence. Documenting those reasons is immensely helpful later on, even if it's only for myself.

If your code requires comments while not doing anything unexpected (like a workaround or a hack) then the code is not that good itself.

I find developers who think comments are never needed even dangerous to the point of vetoing such a hire.

Any developer has been in the situation of reading code and thinking "wtf". Well guess what, creating code is much easier than understanding someone else's code, when someone reads your stuff they may "wtf" just as often, even though you thought your code was clear and self-describing.

Following some strict rules on how to comment well is essential. But commenting is not "giving up", it is an additional tool you have and should use.

On commenting semantics and the Why, - yes, but there are pitfalls. I come across comments where context is given in which a function is intended to operate. This is dangerous when the comment describes something outside the scope it is part of. E.g. the caller of a function might change making a comment describing attributes of the caller faulty. Comments should only be made w.r.t. the scope they are in, otherwise there is a maintenance issue.

Problem: documentation (such as comments) and code can get out of sync.
Solution: just don't document your shit. Yeah cool approach.

Here's an even better one!
Problem: code can have bugs.
Solution: don't write any code at all.

Or even more radical:
Problem: people can get ill, even fatally so.
Solution: hang yourself right away.

In my opinion , sometimes comments are required and necessary. Like in my project. There's a function like (in pseudo code)

```
/**@param blablabla

@param2 blablabla
*/

object name(parametre, parametre){
Obj.setSomthing(somehex);
return something;
}
```

I love the first thing that @Fast-Nop wrote and I think that's the gist of ir for me.

Clean code tells you "what"
A good comments tells you "why"..

Use comments like spice (and sometimes visual delimeters, but some might not agree with that)

Just working on some .bin reading recently and for example all the data is alligned to 16bytes.

If I write clean code to align my data to 16bits you can see clearly what it does, but you wouldn't know why...

But if I add a comment explaining that "the original hardware uses 16byte alignment"

Then you also know why that part of code exists!

A clear separation of concerns between code and comments should exist and if your comments just tell you what the code already tells you then either your code is unreadable and you use it as a crutch or you don't know how use comments well

A few examples of GOOD comments I've seen at work recently:

- My senior coworker ran into a Windows bug and did a workaround. Commented to explain why he didn't do the obvious thing.
- One part of the code measured things in pages (the rest of the code in bytes). Commented explaining why we do this.
- One part of the code looked like a singleton but wasn't because people had cut pieces of it out, comments explained what had happened here.
- Needed to make a class RC to fix a dangling pointer, had to do this instead of the obvious fix because of other code, commented explaining this (and mentioning the relevant sections of code).

If someone tells you never to comment code they're wrong.

Comments should be explaining why you did something, like to work around a bug, because you made certain assumptions, because of other existing code, etc. There are tons of good reasons to comment.

@YADU I agree, I feel this way due the lecturer I had teaching me saying that every line of code needs commented. Every part of a function needs explained and every class needs commented out including a version number etc. It was a pretty self explanitory piece of code, so I wanted to ask if excessive commenting is expected in the workplace.

@GIS-Jedi excessive commenting is definitely bad, just like not having enough comments.

You shoudl generally only comment to explain WHY you did something, which is not going to be nearly every code.

If someone looks at your code and asks "why did you do it like this", either you need to change the code or you need comments (depending on why it's unclear)