Same with BIOS descriptions.
FGTSAB switch [toggles the FGTSAB setting]
infuriating
I love it
It’s so bad it’s almost artistic
You mean autistic.
An autistic coder would have documented this feature to the point of pedantry.
And who updates that documentation three months later when a bug gets fixed or a new requirement get implemented?
The person who changed the code, it’s just ordinary maintenance. The comments may not execute, but I submit they are as much a part of the program as the executable code. Maybe over time those comments are condensed, or even removed; no different than any other refactoring or cleanup.
Yup, my first thought as well. While those days are thankfully over, those braindead BIOS “help” messages remain etched into my mind forever.
Are the recent ones any better? I got a gigabyte b660m for 12th gen intel and it’s really bad at that. Had to look up a lot to figure out things.
Maybe it’s an ASUS thing but both my current and previous boards have been pretty good with the help texts.
Snapmaker Luban is amazing with its help messages.
Every setting in this 3D slicer is completely explained how the setting works, what the different options are, with pictures and even what every option is the most optimal in whatever situation.
Too bad that it isn’t the best program unless you have a Snapmaker, and even then…
Love having to enable “support for sleep state 5” to turn off USB power when the PC is off
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-1997[flashbacks to the backlog being wiped out because “the client already signed off on the release”]
I spent a year making my company’s iOS apps accessible (meaning usable for the blind and people with vision disabilities). I had to do a lot of weird shit either because of bugs in Apple’s VoiceOver technology or because of the strange way in which our code base was broken up into modules (some of which I did not have access to) and I would always put in comments explaining why I was doing what I was doing. The guy doing code review and merges would always just remove my comments (without any other changes) because he felt that not only were comments unnecessary but also they were a “code smell” indicating professional incompetence. I feel sorry for whoever had to deal with that stuff at a later point.
Well, this is shitty
I hope the reviewer did not also squash commits, and the next programmer would be able to at least dig what was there.
Doing changes after some rockstar dev implemented some really complex service, but left no clues as to what does what is so frustrating, and I can never be sure that I don’t break anything in a different place completely
I meant to say commits and not merges, and yes he removed the comments before committing. It made no difference in long run because every new release broke all the accessibility stuff anyway. It’s amazing how little developers can be made to care about blind people - almost as little as managers. The only reason my company cared at all was they were facing million-dollar-a-month fines from the FCC.
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.
/* * 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.I cannot read. Even better.
Makes sense, people looking for int would find a double
Happy cake day!
This being a double physically hurts
//@TODO document this function later15 years later
Have reviewed 16 year old code for a very well known company in the last week with this exact comment peppered throughout, alongside delightfully helpful comments like:
// do not delete or change this it just works// TODO temporary fix added 12/09/11 to fix incident must be removed ASAP// CAUTION this returns false here instead of true like it normally does, not sure why// if true then matched to valid account not is true
Comments should explain “why”, the code already explains “what”.
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
Absolutely, although I see that as part of why
Why is there a horrible hack here? Because stupid reason…
Describing the what also helps when you dabble in a new technology or little-used technology. It helps to explain to yourself what you’re doing and it helps in onboarding. “Hey, newbie, there’s a function in XYZ module that’s extensively documented. Look there for guidance.”
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 don’t code, at best I script. I’m a sysadmin, not a dev, so I play around in PowerShell mostly.
I just started to naturally do all of this. Not because I was taught to, but because I’ve written too many scripts that I later looked at, and thought, WTF is going on here… Who tf wrote this? (Of course it was me)…
So instead of confusing my future self, I started putting in comments. One at the beginning to describe what the file name can’t, and inline comments to step me through what’s happening, and more importantly why I did what I did.
The sheer number of comments can sometimes double the number of lines in my script, but later when I’m staring into the abyss of what I wrote, I appreciate me.
Unless you’re working with people who are too smart, then sometimes the code only explains the how. Why did the log processor have thousands of lines about Hilbert Curves? I never could figure it out even after talking with the person that wrote it.
“Smart”
If you know how the code does something, you also know what it does.
deleted by creator
I write such comments because I have to.
Company policy.
Also we have to specify every line of code and what it should do…
Lol leave. That is so many levels of braindead.
I would smash everything into a handful of overly-complicated lines.
I loved doing this is school, just trying to mess up my teachers.
Sometimes I think after i retire, I should teach. In the hopes that i could inspire people to write good code, instead of a lot of the garbage i see in the industry. This comment makes me sad.
// this line increments the value of i by 1
i++;
I feel like I am going to have to do the same thing in the end, to get my hand-over accepted.
Should I just copy the line of code and make a comment next to it with:// It does <paste line of code>Do you license every comment of yours? If yes, why? Tbh i’m just curious
Not every. The quick, very-low effort ones, I just leave.
Why:
I saw another post with “Anti Commercial AI License”, then wen on to read the license and went, “Neat!”.- It makes it easier for anyone to decide what to do if they want to use my comment/post (in cases where it actually has something useful)
- It makes life just a bit harder for people data-mining for AI
- That way, some data entry worker will probably ask for a raise and probably even get it and maybe some entrepreneur going “AI everywhere!” will think twice.
- Or there will be a chatbot spouting “Anti Commercial AI License” or “CC By-NC-SA” in their answer text, which would be hilarious.
How are you inserting your signature? is it manually? Do you have some kind of keyboard shortcut to insert it?
For now, I have just saved it in my clipboard application, so I copy-paste.
When it goes out of history, I just open a file, where I have saved it and copy from there. So it’s pretty crude.I was hoping that either the KDE Social web interface would add a “Signature” feature or I would pick some Lemmy application that would allow that, but for now it’s just this.
Perhaps, if I feel like it’s being too frequent, I may set a compose key for it.
/********** Setting up the fkuArray **********/
fkuArray = array(…
Well, fku that array indeed.
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.
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.
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.
And isn’t it such a dangerous overlap! The coder whose writing (in their native language) is unclear, repetitive, convoluted, or hard to follow too often produces code with the same qualities. It’s even worse when the same coder believes “code is self-documenting” without considering why. Code self-documents with careful and deliberate effort, and in my experience, it is the really good writers who are most capable of expressing code in this way.
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.
I absolutely agree, and I too hate this stupid idea of “good code documenting itself” and “comments being unnecessary”.
I have a theory where this comes from. It was probably some manager, who has never written a single line of code, who thought that comments were a waste of time, and employees should instead focus on writing code. By telling them that “good code documents itself”, they could also just put the blame on their employees.
“Either you don’t need comments or your code sucks because it’s not self-documenting”
Managers are dumb, and they will never realize that spending a bit of time on writing useful comments may later actually save countless hours, when the project is taken over by a different team, or the people who initially created it, don’t work at the company anymore.I’ve never had a manager that was even aware of the comments vs. no comments issue. If I ever had, I would have just told them that a lack of comments makes the original coder harder to replace.
Code is not self documenting when decision trees are created based on some methodology that’s not extremely obvious
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
Docstring are user documentation, not comments. User documentation, with examples (tests), is always useful.
As long as it’s maintained. Wrong documentation can often be worse than no documentation.
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 <variable name>, or this does <method name>”. 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.
And a good IDE let’s you hide it so… what is your point?
The issue with having mandatory useless comments is that any actually useful comments get lost in the noise.
I get what you’re saying. Perhaps I just haven’t had too many variables and such that have had such comments. VsCode shows the comments on hover when you’re in other parts of the code base. Which makes most any comment useful because something that is obvious in one part of the code isn’t immediately obvious in another. Though, that necessitates making comments that actually help you figure that out.
Comment about image
answer: the answer
The code is self explanatory
/s needed apparently
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.
How bad programmers comment their code. Good programmers don’t comment at all and let the code speak for itself, leaving commenting to some obscure and arcane implementation the coder left in after a week long binge on caffeine and gummy bears.
“What does this section of code do?”
Run it and find out, coward.
Nah. It should be obvious by just looking at it in code. If it isn’t, you haven’t extracted single purpose methods out of it yet.
Just having clear and concise variable names often goes a long way. Avoid using abbreviations.
Breaking out the code into functions helps limit the number of variables within a scope, which makes it easier to name them.
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.
Yeah, hence me mentioning the arcane code nobody knows what it does.
It definitely feels great when I get to remove the
//hack abc due to bug in library xyz version 1.4.5, issue tracker says it’s fixed in 1.5.0. - link
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.
I was rewriting some old code of mine and ended up stripping out the comments. I kept reading them instead of the code, which I had been changing, and they were irrelevant. (I added new comments back in, though a big reason to rewrite was to make the code more self-explanatory.)
Dankpods screen cap?
I don’t know. Anyway, DankPods is awesome, there’s a great Lemmy community dedicated to his channel: [email protected]
Good code is self-explanatory. You should only comment your code if it does something unexpectedly complicated.
That being said, it’s always a good idea to write a manual, about how to use the code. Don’t document how it works, because those who can code will understand it anyways, and those who can’t, have no need to understand it.
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.
Yes. This 1000x. I hate it at work when I come across code that was written 3 years ago that has literally no traces of why it’s there and a quick summary of what it does. Especially because that code is always the most abbreviated spaghetti you’ve ever seen. People should stop thinking (their) code documents itself because 99.999% of programmers cannot do it right.
I really like the Google way of coding: assume the person reading the code is the most 1337 programmer ever, BUT that this person knows absolutely nothing about the project
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.
This is something a lot of people don’t seem to understand. Even if code is self-explanatory, I want to know why it was designed that way.
I’ve fixed bugs where the fix was only a one line change, but it was extremely difficult to figure out, so I left a 10ish line comment above it explaining why it has to be done that way.
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.
Yeah, just 15 seconds and jot down a comment. Whenever I’m even hesitant, I just leave a comment. Doesn’t hurt anything and it can always be removed if not needed
Easier to remove later rather than add it after the fact
If done right, the “what it does” is in the method name. If your method is too complicated to summarize in its name, chances are good you should split it up or extract parts of it.
Hard disagree - that’s just dumb:
// Calculates tax function calculateTax() { }Hard disagree - that’s very helpful:
// Calculates Personal Income Tax by formula from section 1.2.3 of tax code. Other taxes like VAT are not calculated. function calculateTax() { }This guy gets it.
If it calculates personal income tax, just call
calculatePersonalIncomeTax.Is that state, federal, or combined?
Add a flag.
Why not
calculatePersonalIncomeTax123then?I’m a new developer. Is that referring to page 123 of the in-house documentation? Version 12.3 of the code? I have no clue.
You’d have to call it something like calculatePersonalIncomeTaxPerTaxCodeSection1_2_3, but I get exhausted just looking at that. There comes a point where the cognitive work of reading crazy long camel case names is more trouble than it’s worth.
An explanation of what specification a function was written to implement is a perfectly appropriate comment. Could be improved by a direct link where possible. But it’s worth noting what that comment isn’t doing - specifying any implementation details. For that, I really can just read the code.
Yeah, why not?
This is true, but it’s easier and faster to parse plain English and so if I don’t adequately comment my code the first time. I will be commenting it when I have to return to it for whatever reason. Honestly the second round of commenting is more verbose and clearer than the function x does y style of comments I tend to make when coding the first time
Asinine business logic can still make some things very hard to read and digest no matter how well-planned and well-written it is (particularly if it is rushed by the business meaning that engineers don’t have time to do it well). As such, there are places where code can’t/won’t be self-documenting to a useful degree.
Regardless, comments do speed up understanding.
deleted by creator
A real comment in our junior year game engine codebase.
visiblen’t
