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
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.
Out management used to tell us, that even if head of department had committed to doing something some way, there’s no way or need to hold them accountable. It’s just that situation has changed, and nobody should bat an eye.
To be fair, they also did not pressure us much for the missed deadlines or missing features, because it was indeed the result of the situation described in the first paragraph
I was porting our old code from PHP to Go at a previous company. I laughed as I copied my then-six-year-old comment “I’m promised by xxxxx that this is a temporary measure <link to slack convo>”.
/* * 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.
This being a double physically hurts
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
//@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…
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.”
Inline comments yes.
Function/Class/Module doc comments should absolutely explain “what”.
You are absolutely right. It was inline comments I had in mind.
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.
If you know how the code does something, you also know what it does.
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.
// 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.
It’s fine, I wouldn’t want to work with someone who enjoys being forced to comment every line.
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.
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.
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.
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.
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
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.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?
Is that state, federal, or combined?
Add a flag.
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.
Regardless, comments do speed up understanding.
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.
I got a media failed to load error at first and thought that was the joke
deleted by creator
The code is self explanatory
/s needed apparently
It explains what it does, it does not confirm that it is what was intended.
A real comment in our junior year game engine codebase.
visiblen’t
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.
Dankpods screen cap?
I don’t know. Anyway, DankPods is awesome, there’s a great Lemmy community dedicated to his channel: !dingusland@suppo.fi
Looks like it’s from this old reddit post from 6 years ago: https://old.reddit.com/r/ProgrammerHumor/comments/8sviu4/code_comments_be_like/
Fs.?g??yy V>
Same with BIOS descriptions.
FGTSAB switch [toggles the FGTSAB setting]
infuriating
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.
