At work we let Typescript and descriptive naming document our code. Only when something is a workaround or otherwise weird will we add comments. So far it has worked great for us.
Our code base is filled with “//constructor”, “//destructor”, “//assignment”, or the ever enlightening “Foo GetFoo(); // GetFoo”.
This is not what they mean by self-documenting code.
Dankpods screen cap?
I don’t know. Anyway, DankPods is awesome, there’s a great Lemmy community dedicated to his channel: !dingusland@suppo.fi
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.)
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 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 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 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[flashbacks to the backlog being wiped out because “the client already signed off on the release”]
// narrator: the reason was management
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.
Fs.?g??yy V>
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 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”
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…
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
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.”
The code is self explanatory
It explains what it does, it does not confirm that it is what was intended.
The words of the machine are sacred, Only the impure need explanation
/* * 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.I cannot read. Even better.
Makes sense, people looking for int would find a double
Reminds me of a job I had where c# summaries were mandatory and people used a documentation generator just like that.
/// Ages the Category. public int AgeCategory (…)
plenty of APIs in Java have documentation like that and it is worst when I read the documentation in order to find out the definition of the nouns and verbs used there and then it is just like that
Comment about image
Reply about comment about image
answer: the answer
Same with BIOS descriptions.
FGTSAB switch [toggles the FGTSAB setting]
infuriating
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.
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…
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?
Love having to enable “support for sleep state 5” to turn off USB power when the PC is off
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.
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.
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.
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
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() { }If it calculates personal income tax, just call
calculatePersonalIncomeTax.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.
Is that state, federal, or combined?
Add a flag.
This guy gets it.
Regardless, comments do speed up understanding.
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.
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.
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
I got a media failed to load error at first and thought that was the joke
Both jokes can be true 😅
this is why i very rarely comment with descriptive comments. If you’re reading my code and don’t understand what it is, even with how shit it is, you have no business reading whatever fucking crackpot shit im writing.
You must be fun to work with.
you say this like im the type of person to write code with other people.
Doesn’t matter. Even if it’s your code, you might revisit something you made months or a year after doing it and having comments will speed up your work. It’s a very basic good practice.
i do have comments, for some things, but there are a lot of “commenting” standards that are just shit. I find i don’t care what the actual piece of code is doing, i care more about it’s place in the rest of the code, and i’d much rather have “anti comments” instead.
I write such comments because I have to.
Company policy.
Also we have to specify every line of code and what it should do…
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.
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.
Lol leave. That is so many levels of braindead.
// this line increments the value of i by 1
i++;
I hope they get paid per line of code.
I hope i never have to work with you.
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.
I just want to be clear, this was like highschool cs classes. I took things a bit more seriously in college.
I never wrote messy code or illogical code, or any code that didn’t work. We were learning C++ in those days and if you know anything about C++, you can basically cram an entire program into a single line. You can also do some shorthand stuff for calculations and updates to variables… So while the class was instructed to use whitespace and comments and update variables like “var = var + #” I would do var += #… I wouldn’t comment it, mainly out of hubris.
I was pretty good at it but I was lazy as all hell with it.
