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.
It’s cute that you think data miners give a fuck about the license of anything they scrape.
It’s unfortunate that despite explaining as properly as I could, my point was misinterpreted as me relying upon someone caring about licenses.
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.
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.
It’s fine, I wouldn’t want to work with someone who enjoys being forced to comment every line.
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.
deleted by creator
Fs.?g??yy V>
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.
/********** Setting up the fkuArray **********/
fkuArray = array(…
Well, fku that array indeed.
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.
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
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.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?
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.
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.
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.
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.
//@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
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.
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.
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.
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
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 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.
// 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”]
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
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>”.
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
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
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.
I agree.
I usually think of that as documentation, not comments.
But even so, the code should say what it does, with a good name. The documentation adds details.
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
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.
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.)
“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.
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
Yeah, hence me mentioning the arcane code nobody knows what it does.
I got a media failed to load error at first and thought that was the joke
deleted by creator
A real comment in our junior year game engine codebase.
visiblen’t
Dankpods screen cap?
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/
I don’t know. Anyway, DankPods is awesome, there’s a great Lemmy community dedicated to his channel: [email protected]
