I love it

It's so bad it's almost artistic

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

Its definitely a balance. Good code shouldn't need much commenting, but sometimes you have to do something for a reason that isn't immediately obvious and that's when comments are most useful. If you're just explaining what a snippet does instead of why you're doing it that way, there's probably more work to be done.

Good code is self documenting as in you don't need to describe what it is doing and it is clear to read. Whoever says that and isn't just repeating what they heard understands that whenever you are doing something not explicit in the code it should be on a comment.

Workarounds and explaining you need to use this structure instead of another for some reason are clear examples, but business hints are another useful comment. Or sectioning the process (though I prefer descriptive private functions or pragma regions for that).

It also addresses the hint that the code should be readable because you're not going to have comments to explain spaghetti. Just a hint, doesn't prevent it. Others also said it, comments are easier to get outdated as you don't have the compiler to assist. And outdated comments lead to confusion.

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

Code is the what. Comments are the why.

Few things worse than an out of date comment.

Lol leave. That is so many levels of braindead.

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

// this line increments the value of i by 1

i++;

Well, fku that array indeed.

answer: the answer

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.

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