A skilled programmer can make self documenting code, so I always document mine.
73
SeductiveTortoise - 9hr
I inherited a code base probably written by a squirrel, and the first thing I did was to write documentation on infrastructure, business logic, architecture, deployment and whatever. I had to read everything anyways, because the guy handing it over had no idea what it did and left the company shortly after. It's fine now, but that path was horrible.
21
MotoAsh - 5hr
Nah. No code actually documents itself. Ever. Anyone who says they can is an idiot that doesn't understand the purpose of comments and docs.
Code can never describe intent, context, or consequences unless you read every line of code in every library and framework used, and every external call. Especially if they aren't doing "fail fast" correctly.
8
Default Username - 3hr
// Prints "Hello World!" to the screen
printf("Hello World!");
2
MotoAsh - 2hr
I did not say comments should directly explain what the code is obviously attempting to do.
What idiot wrote this? It's complete nonsense... Oh right.
24
Klear - 7hr
Why the fuck would I do this? This is nonsense. This way is way better.
*half an hour later, when I run into a major, strangely familiar bug*
Ooooohhhh!
23
Clent @lemmy.dbzer0.com - 4hr
That's when a "here be dragons" comment needs to be added.
4
tetris11 @feddit.uk - 8hr
A bird in a mouth is worth two in Shepherds Bush
1
RedFrank24 - 10hr
The only times I've seen devs do inline comments in their code is when it's been done by AI, and I can tell it's AI because the comments are all useless and describing what's happening, not why.
47
Eiri @lemmy.ca - 9hr
// Format user object
function formatUserObject(user) {
I've seen lots of such crap written by humans. I guess AI had to learn it from somewhere.
41
Thorry @feddit.org - 9hr
AI mostly learned it from programming tutorials and things like documentation and Q&A forums like StackOverflow. People often add comments in those cases to explain to somebody not familiar with code what is happening so they can learn from it.
In actual code written by people who write code for a living I'd hope the comments are much more useful and usually not as prevalent.
12
definitemaybe @lemmy.ca - 5hr
I actually got really clean, well commented code from Copilot earlier this week.
I have no experience with JavaScript to speak of, but realized a Bookmarklet would be a perfect solution for reformatting a particular arcuate for printing. I already had a head replacement with CSS to do all the formatting, and I was using a RegEx to strip all script tags.
Anyway, I asked Copilot to write the Bookmarklet to replace the header, with full contents explaining the training behind the code, and an explanation of how the script functions below. When I got an error, I asked if to fix the error and or identified that Bookmarklets work better as single lines, so it fixed it. Then I added the requirement about replacing scripts, and it did that too, but for commented and a clean one-line version.
The one-live versions even up getting truncated, so I need to copy/paste from earlier (correct) endings, but otherwise it was an incredibly smooth experience.
I spent longer writing the guide for how to use it than the time it took to vibe code it and test it. I was super impressed.
(Granted, that's a pretty easy coding task...)
2
Clent @lemmy.dbzer0.com - 3hr
no experience with JavaScript to speak of
You claim no JavaScript experience, declare confident in the comments and include any examples.
All you've really said here is you vibed coded a solution to a problem using one of the most common languages without knowing the language. And made claims you do not attempt to prove.
1
konalt - 10hr
// 🚨 Log error to console console.error(error);
25
Thorry @feddit.org - 9hr
// 🤦 You are totally right! Simply logging the 🚨 error to the console isn't proper error handling. 🫣 We now throw an exception instead. throw new ApplicationException(error);
18
tauonite @lemmy.world - 53min
I once tried vibe coding a web app using GitHub Copilot. That motherfucker wrapped every single endpoint with
What the fuck is wrong with you Copilot? This piece of shit trying to hide all the errors. If I don't know there are errors then there aren't errors. Apparently
1
nogooduser @lemmy.world - 9hr
I sometimes suspect that I am actually an AI. I’ve always struggled with captchas and I comment my code exactly as you’ve just described.
9
vrek @programming.dev - 5hr
Proper comments describe why... For example say you are using an api which requires guids and your application doesn't care are collisions as much so just use int id's.
You could add in a comment like
// creating a guid to interface with special api.
But just saying
// generate guid
Means nothing, your method should be generate_guid() or GenerateGuid(). Your comment is repeating.
Or this is probably going to hit my last company at some point, there was a system to read a serial number. They also wanted a "status" on the screen to verify the system was connected and running properly but both these values came over same signal wire. Depending on your exact ms timing sometimes you would read the status as the serial number. Another programmer wrote a check to verify the serial number did not start with OK. The comment added was
// add on 11/15/23 by Initials
With no other details. The serial numbers were 8 numeric digits. Someone won't know the history and delete this seemingly useless check and cause a 10s of 1000s of dollars in loss
4
anomnom @sh.itjust.works - 5hr
I used to write it all the steps I thought I’d need as these types of comments, then go back and write the real methods. But I usually replaced the comments with more detailed jsdocs style comments with as much detail about the parameters as returnvalues as possible.
Then I quit web dev and moved to the woods.
3
vrek @programming.dev - 4hr
Yeah effectively using comments as psuedocode
2
Eager Eagle - 9hr
yeah, I put rules to highly discourage comments entirely when generating code
2
MonkderVierte @lemmy.zip - 8hr
I do add a invocation comment to my shell functions. Because parsing what is happening why, is so much more effort the next time i touch it two years later. Despite the code being as clean as possible.
1
jubilationtcornpone @sh.itjust.works - 8hr
/*
By all accounts, the logic in this method shouldn't work. And yet it does. We do not know why. It makes no sense whatsoever. It took three weeks and numerous offerings to the programming gods, including using one of the junior devs as a human sacrifice, to unlock this knowledge. DO NOT LET HIS VIOLENT AND UNTIMELY DEATH BE IN VAIN! Touch this at your own peril.
--jubilationtcornpone 12/17/25
*/
public async Task<IResult> CalculateResultAsync()
{
// Some ass backwards yet miraculously functional logic.
}
33
HairyHarry @lemmy.world - 10hr
Decoding hieroglyphs with an English dictionary should do the work.
33
bonenode - 10hr
Especially helpful that it is written right to left. Maybe the Manga version of the English dictionary.
I'm living this right now. The lead programmers are long gone for a setup that uses Python, C++, and Linux. The only other guy who knows it is pulled to three other projects and I only have a C++ class taken over 15 years ago under my belt. I'm somehow expected to decipher this shit and explain the function of a few dozen variables and it's going as well as one might expect.
11
leo85811nardo @lemmy.world - 10hr
Looks like me vs my code after the winter holiday break
10
SleeplessCityLights @programming.dev - 9hr
I started writing a giant note. On the last day in the morning I start it and add anything that I need to do after the break to it. These are very highly detailed including line numbers ro point me at the exact spot I need, names of bookmarks for reference, page number on documentation, anything that is going to unfuck the morning of the first day I come back.
6
xxce2AAb @feddit.dk - 9hr
"According to all available documentation, your code is utter shit."
10
☂️- - 2hr
who the fuck wrote this garbage
me. its just me every time.
5
SaharaMaleikuhm @feddit.org - 7hr
Post AI slop image -> get blocked
5
Goldholz - 9hr
That would be me and i now know im wrong.
Paradox Interactives Documentation is terrible
skepller in programmer_humor @programming.dev
My code is self-documenting
A skilled programmer can make self documenting code, so I always document mine.
I inherited a code base probably written by a squirrel, and the first thing I did was to write documentation on infrastructure, business logic, architecture, deployment and whatever. I had to read everything anyways, because the guy handing it over had no idea what it did and left the company shortly after. It's fine now, but that path was horrible.
Nah. No code actually documents itself. Ever. Anyone who says they can is an idiot that doesn't understand the purpose of comments and docs.
Code can never describe intent, context, or consequences unless you read every line of code in every library and framework used, and every external call. Especially if they aren't doing "fail fast" correctly.
I did not say comments should directly explain what the code is obviously attempting to do.
https://quokk.au/static/media/posts/oa/3d/oa3d1kEtbrOopEn.png
What idiot wrote this? It's complete nonsense... Oh right.
Why the fuck would I do this? This is nonsense. This way is way better.
*half an hour later, when I run into a major, strangely familiar bug*
Ooooohhhh!
That's when a "here be dragons" comment needs to be added.
A bird in a mouth is worth two in Shepherds Bush
The only times I've seen devs do inline comments in their code is when it's been done by AI, and I can tell it's AI because the comments are all useless and describing what's happening, not why.
I've seen lots of such crap written by humans. I guess AI had to learn it from somewhere.
AI mostly learned it from programming tutorials and things like documentation and Q&A forums like StackOverflow. People often add comments in those cases to explain to somebody not familiar with code what is happening so they can learn from it.
In actual code written by people who write code for a living I'd hope the comments are much more useful and usually not as prevalent.
I actually got really clean, well commented code from Copilot earlier this week.
I have no experience with JavaScript to speak of, but realized a Bookmarklet would be a perfect solution for reformatting a particular arcuate for printing. I already had a head replacement with CSS to do all the formatting, and I was using a RegEx to strip all script tags.
Anyway, I asked Copilot to write the Bookmarklet to replace the header, with full contents explaining the training behind the code, and an explanation of how the script functions below. When I got an error, I asked if to fix the error and or identified that Bookmarklets work better as single lines, so it fixed it. Then I added the requirement about replacing scripts, and it did that too, but for commented and a clean one-line version.
The one-live versions even up getting truncated, so I need to copy/paste from earlier (correct) endings, but otherwise it was an incredibly smooth experience.
I spent longer writing the guide for how to use it than the time it took to vibe code it and test it. I was super impressed.
(Granted, that's a pretty easy coding task...)
You claim no JavaScript experience, declare confident in the comments and include any examples.
All you've really said here is you vibed coded a solution to a problem using one of the most common languages without knowing the language. And made claims you do not attempt to prove.
// 🚨 Log error to console console.error(error);// 🤦 You are totally right! Simply logging the 🚨 error to the console isn't proper error handling. 🫣 We now throw an exception instead. throw new ApplicationException(error);I once tried vibe coding a web app using GitHub Copilot. That motherfucker wrapped every single endpoint with
What the fuck is wrong with you Copilot? This piece of shit trying to hide all the errors. If I don't know there are errors then there aren't errors. Apparently
I sometimes suspect that I am actually an AI. I’ve always struggled with captchas and I comment my code exactly as you’ve just described.
Proper comments describe why... For example say you are using an api which requires guids and your application doesn't care are collisions as much so just use int id's.
You could add in a comment like
// creating a guid to interface with special api.
But just saying
// generate guid
Means nothing, your method should be generate_guid() or GenerateGuid(). Your comment is repeating.
Or this is probably going to hit my last company at some point, there was a system to read a serial number. They also wanted a "status" on the screen to verify the system was connected and running properly but both these values came over same signal wire. Depending on your exact ms timing sometimes you would read the status as the serial number. Another programmer wrote a check to verify the serial number did not start with OK. The comment added was
// add on 11/15/23 by Initials
With no other details. The serial numbers were 8 numeric digits. Someone won't know the history and delete this seemingly useless check and cause a 10s of 1000s of dollars in loss
I used to write it all the steps I thought I’d need as these types of comments, then go back and write the real methods. But I usually replaced the comments with more detailed jsdocs style comments with as much detail about the parameters as returnvalues as possible.
Then I quit web dev and moved to the woods.
Yeah effectively using comments as psuedocode
yeah, I put rules to highly discourage comments entirely when generating code
I do add a invocation comment to my shell functions. Because parsing what is happening why, is so much more effort the next time i touch it two years later. Despite the code being as clean as possible.
Decoding hieroglyphs with an English dictionary should do the work.
Especially helpful that it is written right to left. Maybe the Manga version of the English dictionary.
It is not.
Who wrote this shit?!
Oh, it was me. Last month.
Fixed:
https://lemmy.world/pictrs/image/018229ed-4bf8-4d8f-a331-44526ff99512.png
https://lemmy.world/pictrs/image/2d32b04d-2b88-4caa-9b61-48d68d1b29f5.jpeg
Every time.
Now do one for PL/SQL.
I have left this as an exercise for the reader.
Wait until you write code that is self-hosting!
I'm living this right now. The lead programmers are long gone for a setup that uses Python, C++, and Linux. The only other guy who knows it is pulled to three other projects and I only have a C++ class taken over 15 years ago under my belt. I'm somehow expected to decipher this shit and explain the function of a few dozen variables and it's going as well as one might expect.
Looks like me vs my code after the winter holiday break
I started writing a giant note. On the last day in the morning I start it and add anything that I need to do after the break to it. These are very highly detailed including line numbers ro point me at the exact spot I need, names of bookmarks for reference, page number on documentation, anything that is going to unfuck the morning of the first day I come back.
"According to all available documentation, your code is utter shit."
me. its just me every time.
Post AI slop image -> get blocked
That would be me and i now know im wrong. Paradox Interactives Documentation is terrible
Just ask AI to figure it out.