//@TODO document this function later15 years later
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
/* * Gets stupidFuckingInteger * * @returns stupidFuckingInteger */ public double getStupidFuckingInteger() { return stupidFuckingInteger; }This being a double physically hurts
The lack of a return type declaration makes this sooo good.
It has the return type declared to be
double.
Comments should explain “why”, the code already explains “what”.
deleted by creator
Absolutely, although I see that as part of why
Why is there a horrible hack here? Because stupid reason…
Or if the what is so cryptic and esoteric that it would require the reader a couple hours of research to understand it.
Also, I find it useful to summarise the what before code blocks if that can’t be summarised in a function name
Inline comments yes.
Function/Class/Module doc comments should absolutely explain “what”.
You are absolutely right. It was inline comments I had in mind.
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// narrator: the reason was management
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.
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.
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
