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.
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:
<span style="font-style:italic;color:#969896;">// It does <paste line of code>
</span>
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.
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.
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
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.
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…
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
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.”
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.
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.
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 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.
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.
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>".
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.
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.)
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.
Did you read all the way to the end of the article? I did.
At the very bottom of the piece, I found that the author had already expressed what I wanted to say quite well:
In my humble opinion, here’s the key takeaway: just write your own fucking constructors! You see all that nonsense? Almost completely avoidable if you had just written your own fucking constructors. Don’t let the compiler figure it out for you. You’re the one in control here.
The joke here isn’t C++. The joke is people who expect C++ to be as warm, fuzzy, and forgiving as JavaScript.
programmer_humor
Hot
This magazine is from a federated server and may be incomplete. Browse more on the original instance.