"Do not comment on your code, it should be self-documented". Well... I don't agree.

It's never 'useless', but it can be overkill.

If code is written well (good variable & function names, clear logic), then it should be fairly obvious from reading it what it does. In cases where the logic is a little hard to follow then some comments can be very helpful. It can be a tricky balance - you don't want absolutely no comments ever, but at the same time, commenting absolutely everything just to try and cater for every possible skill level is also not a good idea.

If code is written well, and is uncommented - then it is probably the assumption of the team (as presumably the code has passed code review) that it is already understandable enough. If a new developer comes to this code and does not understand it, the best solution would be to consult a team member who does, and get them to explain it. This will have the dual benefit of increasing the junior developer's understanding, and making the team aware that there may be an issue with the code being too impenetrable in places.

I've never in my years of education been told (except from that student who doesn't want to comment their code) that commenting/documenting code is "useless". Oh my! Documenting your code teaches beginners what you're doing. Not documenting at all excludes them because....how are they supposed to understand if you don't explain it in plain english? I bet the developer himself/herself won't even remember what the program he or she wrote does five or six months down the line without documentation. Who is it harming? True productivity, team work, and efficiency? Or just their ego and arrogance?

My golden rules:

Add a summary at the top of a function about what it does.

This way I do not have to read and mentally parse your functions code to understand what it does.
This does not apply to very simple functions where the function name can describe everything like removeLastCharacter(). But calculateSingularityProbability() might win by some description.

Add comments to reduce mental work

If some line(s) are really complicated, add a short comment above describing what it does.

Add comments to explain hidden knowledge

Why are you doing array.pop() twice here without any appearant reason? Well, because I do know that the array always contains two empty entries at the end, which we don't want.
If you write the code, you have that knowledge at hand. Your team member might not. And you, looking at that code in 2 month wont remember either.

Agreed big, and so few developers know that I always hear those words and I can't argue.
Best line ever:
"Not commenting on your code is narcissist and excludes beginners, btw."

"Who said your code is as good and obvious as you think it is? Yeah, your mind." Yes Yes Yes a lot of developers say it and yes it's only good in your mind even the seniors will struggle with undocumented code.

Although I do see your point, and I myself tend to "over comment" my own code, there is a valid argument to the code being self documented. Interestingly, with a "meta programming" language, such as our Hyperlambda, the code literally is self documented, due to the abilities of the programming language to extract meta data from the code, being able to intelligently understand what each snippet of code does, to the point where you can write stuff that's logically similar to the following (pseudo code).

select c.filename from codebase c where c.code invokes(log)

Of course the above is pseudo code, but still a perfectly example of something easily achieved with a "meta programming language", resulting in that your "comments" literally becomes its code, and information about what the code does can be dynamically extracted using automated processes, allowing you to easily understand everything your code actually does, without having a single comment in your code base.

Still, kind of out of fear from possibly being wrong, I tend to document my code (too much) ... :/

I intend to write a full post about this sometime, but here are my thoughts in summary.

Self-documenting code doesn't exist because the purpose of documentation is different from what clean code gives you. Cleanly written code makes it trivial to understand how the code functions — nothing surprises you, the code isn't hard to follow or constructed of spaghetti, chunks of it fit neatly in your memory and it doesn't require you to go back-and-forth too often. You understand both the implementation and the abstraction quickly and cleanly. It exposes all of the how and most of the what, but what it doesn't necessarily do is explain all of the why.

Sure, well-written clean code with properly named functions and properties etc. can help expose the why, but it still requires you to do several iterative readings in any sizeable codebase to grasp the original business intent — namely, why does this code exist at all? What purpose does it serve?

That's where documentation steps in. Documentation should expose as much of the why as possible, and some of the what, without focusing at all on the how, since how it is implemented is quite literally implementation detail, and is subject to change even without the original business intent changing. The why changes very rarely, and also requires the least comprehensive documentation (the type of documentation that Agile tries to avoid) which is quick to read and grasp.

In my experience, pretty much every programmer I've met who has clamored for "don't write documentation, write self-documenting code" has parroted this statement because they didn't want to spend the time it takes to write documentation in the first place, not because they genuinely believe trawling through the code trying to tenuously grasp the intent of its writing is better than reading a short document about it.

I've always found this to be a pretty egotist attitude. "My code is so good you shouldn't need help to understand it".
I've learnt there's a balance in commenting. There are really 3 use cases:

• you need to explain the "why" of a function or a piece of code. Not the "how" or the "what", which should be clear from the code
• a function has very complex or business-specific logic and it's 100x easier to talk the reader through what is happening than to just hope they can follow all the branches and call chains
• you need to explain/excuse something stupid of illogical with how a 3rd party library or api works. If I find myself in this situation I often consider whether I'm using the best library for the job...

During your work, probably you faced a function that you asked yourself: "-What the hell is even that?"

Yes, but that's not so much because I didn't comment the code, as that I didn't write clean, readable code in the first place. If the bit of my wetware that needed to light up at the time to tell me to comment it had actually been doing its job I'd have written it better anyway!

Mostly, I'm on your side in this. I like commenting things. I like having a standard doc comment at the top of every function, even if it's "obvious".

However, I've had colleagues who don't, and their arguments are usually something like, "now you have to update two things", i.e. whenever you make a code change you need to make sure the comments and documentation match, and it's way too easy to forget. In fact, how many times have you seen the same comment repeated because someone's copied a component from one file to another to use as a kind of boilerplate, even though it has an entirely new purpose now?

I'm so happy to see so rich discussion here in my article! Thank you so much devs.

I guess that it is necessary some context, but to make it short:

• High-level comments explaining what (not how) a specific function/package/class does is useful since allows the reader to orient itself in the code. Also, that is the kind of information that does not change frequently, so the probability that the comment gets stale is minimal
• Comments to explain a non-trivial algorithm (e.g., the Euclidean GCD) can be useful, also to keep track of the conditions that are true at every point. Here assertions, loop invariant and similar stuff are your friend since they allow you to document what is going on in a way that the compiler can check, minimizing the probability of getting stale
• Comments that explain why something is done. This is quite uncommon, in my experience, but it happens every now and then. Maybe there is a counter-intuitive way to do the things or maybe there is a strange check that seems useless and you would be tempted to "optimize it away," but it actually takes care of some borderline case that it is not easy to imagine.
• The kind of comments that are wrong are maybe the most common ones that try to clarify what would had been clear if the code were written nicely. For example, instead of writing this

int d;
int c;      /* total cost */
int e[7];  /* daily expense */

for (d=0; d<7; d++) // Loop over the week
{ c = c + e[d];}

better this

int week_day;
int total_cost;
int daily_expense[7];

for (week_day=0; week_day < 7; week_day++)
{  total_cost = total_cost + daily_expense[week_day]; }

I don't think leaving out comments excludes beginners. Quite the opposite. Writing too much waste into your code sets a bad example. And I've seen more redundant comments than useful ones in codebases I worked on (including my own).

My favourite to this day is:

// Initial request to vendor API
// ... 3 uninformative lines explaining what's going on
// TODO: If fails, figure something out. First request should never fail
function getStuffFirstTime() { ... }

Does this look beginner friendly to you?

If you do want to comment stuff, please write proper JavaDoc / JSDoc / whatever-Doc. That's what it's there for.

• Use @desc, @property/s and @returns.
• Give a 2-liner about what your code does if you must
• If you must use a comment inline, you will probably be better off refactoring your function or method anyway

And if you want to go bonkers, at least be so kind and do so in your automated test suites. You can even use @see in your production code base. And everybody wins.

Great article! Writing comments about what your code does can be helpful. But, I've learned that writing too many comments can be excessive.

I use comments in the code very sparingly and only to tell the story about the reasoning behind the code if that should not be obvious even to a beginner.

I'm very liberal with elaborate JSDoc blocks above my API interfaces, though.

The line I always take with students I mentor is that I don't need a comment to tell me what the code is doing, because I can read the code just fine, and most of that can be encoded in variable and function names, like frobnicate_the_input_array() and input_array_to_frobnicate. I need comments to tell me why it's doing that, and particularly why you're not doing it a different way.

"But requirements and statements of purpose don't belong in the code! They should be in other requirements documents." As a developer, I have ready access to the code I'm working on, not the requirements docs, and I especially don't have anything to connect frobnicate_the_input_array to a requirements doc saying that the input array needs to be frobnicated, or to a later decision saying that it needs to be frobbed in reverse order. That's what I need a comment for.

This is a straw man argument. I don't know a single developer who never writes a comment. The argument is over whether you should comment everything, or just when a comment is needed, which is inversely proportional to the amount of clean, readable, and easily understandable code you write. The argument is not that you should never comment your code.

If you have to make up a straw man argument, then your credibility as an authority is undermined.