Same with BIOS descriptions.
FGTSAB switch [toggles the FGTSAB setting]
infuriating
this post was submitted on 06 Jul 2024
23 points (96.0% liked)
Programmer Humor
32896 readers
301 users here now
Welcome to Programmer Humor!
This is a place where you can post jokes, memes, humor, etc. related to programming!
For sharing awful code theres also Programming Horror.
Rules
- Keep content in english
- No advertisements
- Posts must be related to programming or programmer topics
founded 3 years ago
MODERATORS
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.
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.
// narrator: the reason was management
// I told them I'd do this but only if they gave me time next sprint to fix it - 12-03-1997The 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.
//@TODO document this function later
15 years later
/*
* Gets stupidFuckingInteger
*
* @returns stupidFuckingInteger
*/
public double getStupidFuckingInteger() {
return stupidFuckingInteger;
}
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".
Inline comments yes.
Function/Class/Module doc comments should absolutely explain "what".
You are absolutely right. It was inline comments I had in mind.
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 is the what. Comments are the why.
Few things worse than an out of date comment.
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 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.
The code is self explanatory
/s needed apparently
The words of the machine are sacred, Only the impure need explanation
