Programmer Humor

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.

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".

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.

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.

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.

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

It explains what it does, it does not confirm that it is what was intended.

"What does this section of code do?"

Run it and find out, coward.

Code should absolutely speak for itself. But the occasional comment is still good to explain the 'why' of the code when the why isn't very obvious, often due to a niche requirement. Also any time you have to break out a hack, that needs comments up the ass, what was the bug, what URL did you find the fix at, why does this hack work, etc etc. It's very satisfying to go back and remove those hacks after they are no longer needed, often because the underlying technology fixed the bug that had to be hacked around.

This is the truth. In my experience, the people who often writes comments are also writing the most incomprehensible code.

Comments are frequently getting outdated as well, so they’re not in great help understanding the code either.