Yeah, good code should explain the "what" without the need for comments. Good comments explain the "why".

I used to work with a guy who insisted his code was self explanatory, and then he'd nest loops 5 levels deep and give variables names like "thingyOne".

I had a boss who hated comments because he wanted "clean code," and that comments means you aren't using the wiki. The build approval process actually stripped out all comments via a script.

Then we lost the wiki.

It kind of feels like engineers look for simple solutions to what are ultimately complicated psychological questions sometimes.

The vitriol the "Clean Code" cult has against comments is unbelievable...

They do have a point though. When we’ve gone through phases where the industry focuses on commenting code and other documentation, most of it is useless.

Code comments should have a reason, and are no substitute for readable code.

However you’re also right though that people jump onto “all or nothing”. I recently did a code Review that I held up for comments. In this case, they were doing something very atypical to get around a limitation so it was a clear case of comments needed. The next person through will say “what is this shit?” And “fix” it, without knowing there was a good reason

That's silly. I've never seen comments even as a way to explain what your code is doing (the code often does do that anyway). It's important to say WHY you're doing it the way you are.

That way anyone else who comes in there can have the same context you did when you implemented it, which imo is where most bugs occur. People don't realize what assumptions you made when it was first written, and then make their own (which can easily clash).

Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?

Brian Kernighan - The Elements of Programming Style, 2nd edition, chapter 2

A similar phenomenon is knowing you're going to need to go back and update some older section of code and when you finally get around to it, it turns out you wrote it that way to begin with. It's like... I didn't think I knew about this approach before...

"I'm dumber but wiser" - me, hopefully

My favorite is the 'here be dragons' ASCII art, that's how you know you're in for a fun time

"Code is the documentation"

Is the laziest excuse I've come across. Like, not everyone knows everything and complex code exists, it is not hard to put in some text explaining the basics of what something does.

Like, unless you're dealing with that code everyday it's going to look like double dutch to anyone new coming to it.

I've had people say that to me before, and it is absolutely infuriating in its laziness and cop out excuse.

The code shows what happens. But comments should explain why it was done this way.

Sometimes the code started simple and readable, till you ran into a weird edge case a year ago. Now the code no longer looks as obvious and another developer might scratch their head when they read over it. A small comment can help out there quite a bit.

Or you're doing something stupid in code not because you want to, but because management forced you to. So you put a comment there that the code isn't wrong, management wanted that behavior.

Ah, I see you don't optimise enough.

It should be...

Past you "I've shed so many lines and boosted processing time. It's a masterpiece. I should document this for future me because it's complex as hell."

Future you "What. The. Hell..." five minutes later "Oh, I see. I'm a fucking narcissist trying to be god of something 10 people run once a week."