/* * Gets stupidFuckingInteger * * @returns stupidFuckingInteger */ public double getStupidFuckingInteger() { return stupidFuckingInteger; }This being a double physically hurts
Same with BIOS descriptions.
FGTSAB switch [toggles the FGTSAB setting]
infuriating
Yup, my first thought as well. While those days are thankfully over, those braindead BIOS “help” messages remain etched into my mind forever.
I love it
//@TODO document this function later15 years later
I had a old job that told me that code is “self documenting” if you write it “good enough”. And that comments were unnecessary.
It always annoyed the heck out of me. Comments are imo more helpful than hurtful typically.
Is it just me? Or am I weird? Lol.
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.
lazy programmers
I don’t think they’re lazy, I think they’re not good writers. Not being able to write well is very common among programmers (not having to communicate with written language is one reason a lot of people go into coding) and in my experience the Venn diagrams for “not a good writer” and “thinks comments are unnecessary” overlap perfectly.
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.
The code is self explanatory
/s needed apparently
The words of the machine are sacred, Only the impure need explanation
Best comment ever was “It used to work like this but person at client demanded it work like that on this date” when the client complained it shouldn’t work like that.
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.
// I'm not really that dumb, there is a reason.// I told them I'd do this but only if they gave me time next sprint to fix it - 12-03-1997
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.