Programmer Humor

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.

Have you ever worked in a place where every function/field needed a comment? Most of those comments end up being "This is the , or this does ". Beyond, being useless, those comments are counter productive. The amount of screen space they take up (even if greyed out by the IDE) significantly hurts legability.

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