It's so bad it's almost artistic

I love it

Yup, my first thought as well. While those days are thankfully over, those braindead BIOS "help" messages remain etched into my mind forever.

That's basically what comments are most useful for. When you're doing something that's not obvious, and want to make sure the "why" doesn't get lost to time.

The best comments are "why" comments, the runner up is "how" comments if high-level enough, and maybe just don't write "what" comments at all because everyone reading your code knows how to read code.

this seems like a great idea as it provides proof in writing just in case the stakeholder complains later on about the thing you implemented at their request

That’s actually the perfect comment, because if anyone ever comes back to fuck with you about it, it’s explained right there. Then you turn it right back around on management and watch them run around like chickens with their heads cut off.

The lack of a return type declaration makes this sooo good.

This being a double physically hurts

Makes sense, people looking for int would find a double

The allowable exception is when the what is a what the fuck, as in you had to use a hack so horrible that it requires an apology comment

Inline comments yes.

Function/Class/Module doc comments should absolutely explain "what".

Document intentions and decisions, not code.

Code should always by itself document the "how" of the code, otherwise the code most likely isn't good enough. Something the code can never do is explain the "why" of the code, something that a lot of programmers skip. If you ever find yourself explaining the "how" in the comments, maybe run through the code once more and see if something can be simplified or variables can get more descriptive names.

For me, that's what was originally meant with self-documenting code. A shame lazy programmers hijacked the term in order to avoid writing any documentation.

Comment should describe "why?", not "how?", or "what?", and only when the "why?" is not intuitive.

The problem with comments arise when you update the code but not the comments. This leads to incorrect comments, which might do more harm than no comments at all.

E.g. Good comment: "This workaround is due to a bug in xyz"

Bad comment: "Set variable x to value y"

Note: this only concerns code comments, docstrings are still a good idea, as long as they are maintained

Code is the what. Comments are the why.

Few things worse than an out of date comment.

In my opinion, it strongly depends on what you're coding.

Low-level code where you need to initialize array indices to represent certain flags? ~~Absolutely comment the living shit out of that.~~ → See response.
High-level code where you're just plumbing different libraries? Hell no, the code is just as easily readable as a comment.

I do also think that, no matter where you lie in this spectrum, there is always merit to improving code to reduce the need for documentation:

• Rather than typing out the specification, write a unit/integration test.
• Rather than describing that a function should only be called in a certain way, make it impossible to do it wrongly by modelling this in your type system.
• Rather than adding a comment to describe what a block of code does, pull it out into a separate function.
• Rather than explaining how a snippet of code works, try to simplify it, so this becomes obvious.

The thing with documentation is that it merely makes it easier to learn about complexity, whereas a code improvement may eliminate this complexity or the need to know about it, because the compiler/test will remember.

This does not mean you should avoid comments like they're actively bad. As many others said, particularly the "why" is not expressable in code. Sometimes, it is also genuinely not possible to clean up a snippet of code enough that it becomes digestable.
But it is still a good idea, when you feel the need to leave a comment that explains something else than the "why", to consider for a moment, if there's not some code improvement you should be doing instead.

Code is not self documenting when decision trees are created based on some methodology that's not extremely obvious

Lol leave. That is so many levels of braindead.

I would smash everything into a handful of overly-complicated lines.

Well, fku that array indeed.

Good code is self-explanatory. You should only comment your code if it does something unexpectedly complicated.

The code shows what is being done. The comments should explain the why.

Hard disagree. It's a lot easier and faster to understand a function that is prefaced with a small line of text explaining what it does rather than trying to figure it out yourself.

It's not about whether you can understand the code or not, it's about efficiency and clarity.

The words of the machine are sacred, Only the impure need explanation