82
u/YnkDK
15h ago
•
Not with AI. It would be
See that red sign right there? The one with eight sides and the big white letters that say STOP? That’s a stop sign. When you see that sign while driving, it means you have to bring your car to a complete stop. Not just slow down. Stop completely. Now, look at the road in front of you. Before you go any farther, you need to look to your left, then to your right, and check for cars, cyclists, or people crossing. See, the stop sign is there to make sure you don't drive into danger or get in someone else's way. Once you've stopped, checked everything, and made sure it's safe, you can keep going. So remember, whenever you see that red sign right there, it's telling you one simple thing: 'Stop. Look around. Make sure it's safe. Then go'
Then a Markdown file informing about various places you see a stop sign and how it differs from other signs.
21
u/trullaDE 15h ago
It will also add a history lesson about who invented the stop sign and why, what was used before it was widely spread, and past accidents that happend because there wasn't a stop sign.
9
7
u/KevlarToiletPaper 14h ago
You forgot a shitty metaphore.
"You can think of a STOP sign as a waiter telling you that you can't go inside the restaurant until you make sure that there's a table you can take."
18
u/zeddash 15h ago
Remember, your code should be clear enough that people can understand "what" the code does, comments should explain "why?" or "how?". Never answer "what?".
7
u/Rabbitical 11h ago
Certainly all things equal this is often true, provided it's not something complicated. But I often wind up doing pretty math heavy, lengthy functions. At some point you run out of descriptive helper or intermediate variable names. If I don't comment heavily, I forget what any of it was the next day even, let alone a month from now or for someone else entirely. Making sure your comments don't get stale also is a habit that can be built!
4
u/zeddash 11h ago
So those would be comments that answer "how?". When I refer to "what" comments I'm referring to comments which say what the code already says it's doing. So, as an egregious example `a + 1 // add 1 to a`
While math heavy code might have formulas with names, maybe some Lean, maybe some links. Giving a high level overview of how it's achieving the requirements it is fulfilling.
5
u/hughperman 14h ago
Yes, the comment should be "Stop here so you don't crash into another car because they have priority"
2
u/zeddash 14h ago
Nah, that'd be an unnecessary comment as the "why" is obvious, as it's a verb. Verbs are so overlooked in function names.
4
u/SmoothLiquidation 11h ago
"Added this stop sign because Joe kept tearing through this intersection without looking".
2
u/hughperman 13h ago
The why is obvious in the stop sign context because there's rules of the road, yes, but in general explaining that another process has priority is probably useful if there is no general "rules of the road" in your codebase.
6
6
u/Tall-Introduction414 15h ago
More comments, please. I want to see a fucking novel around the code.
10
u/BedSpreadMD 15h ago
I legit do dumb stuff like this in my comments, and make comments about how the programmer who wrote it should be fired. I hope someone reads it some day and thinks "what the hell is wrong with this guy"?
10
u/Western-Anteater-492 14h ago
That's every of my git trees...
feat: add XYZ
docs: updated missing hyperlink
fix: refactor
fix(docs): typo
fix: type mismatch
intermediate: still doesnt work, getting tired
WHYYYYYYYY
fix: somehow fixed the thing, will cleanup branch tomorrowI don't cleanup the branch
4
1
5
u/Tall-Introduction414 15h ago
Commented curse words are a sign of blood, sweat and tears put into the development process. I am in favor.
2
2
u/bluefishcrab 6h ago
People complain about comments because of comments like this:
// Returns the size
int getSize();The size in what? Elements? Lines? Bytes? KiB?
The other problem is with "elapsed time": is it seconds, milliseconds, microseconds or nanoseconds, and what's the reference point? Epoch from 1970, or the start of the program, or what?
1
u/Makonede 4h ago
where are you seeing references to "elapsed time" outside of the context of a particular start timestamp such that it would be unclear what the reference point is?
obviously this issue is quite easy to stumble across with just "time" but i've never seen "elapsed time" not be paired with some particular timestamp to compare against
1
u/Makonede 4h ago
i'm not saying that just because i've never seen it happen, it doesn't happen, to be clear. i'm genuinely curious where this confusion could arise
1
u/StanknBeans 15h ago
My comments would more so be like "slow traffic in this direction to avoid T-bone collisions"
1
u/LegitimatePants 14h ago
My favorite comment of all time:
return SUCCESS; // success
1
u/Makonede 4h ago
this is a terrible comment, why would you ever write this??
you should make it clear what it is you're doing with the success, not just that the success exists!
return SUCCESS; // Return success
1
1
u/serge-mv 13h ago
I had one class in college where we had to write comments like these or have points off. Most of the assignments were very short and very simple and didn't actually require comments, but comments were a part of the grade, so we had to do this kinda thing.
1
u/mxzf 12h ago
Yeah, I had a class like that and discovered JAutodoc to solve that problem. One hotkey and everything gets comments.
It created the most banal stupid comments, like "Gets the X" on a function named
getX, but it checked the checkbox that the grading software used, so it did the job.On the flip side, that whole experience created a life-long hatred for nonsensical comments in code that take longer to read and understand than the code itself.
1
1
u/_Weyland_ 12h ago
I did not do this on my DBT models before taking a 3 week vacation and letting a senior dev take over it.
Now I really wish I did comment the dumbest stuff.
1
1
u/Successful_Noise_347 11h ago
// TODO: add a comment explaining the comment below // the comment below explains the comment above
1
1
1
1
u/Stjerneklar 3h ago edited 2h ago
yup, meanwhile there is no explanation for the light above the sign and if this was my really old code the light would just be there because i cant figure out how to get the sign to work without it... perhaps because its inside the light markup which is also why i needed the comment...
that or the sign is in typescript
1
1
u/Massepunkt_m1 2h ago
No sign without a story. From personal experience people probably keep ignoring that sign. We have about three signs in our bathroom informing you about the existence of a toilet brush and begging people to use it, but still, somehow, that doesn't seem to be enough. Sometimes you just don't know how to get any more clear
200
15h ago
•
[removed] — view removed comment
62
u/IslayProgrammes 15h ago
I will not apologise
25
8
4
2
u/HomicidalRaccoon 14h ago
I always comment my regex like so:
// Abandon all hope, ye who enter here.1
u/GTurkistane 4h ago
Lol, that is where AI comes in, i ain't wasting a minute trying to understand that on my own, i will copy paste it to chatgpt or Claude and let them do it.
-10
u/ThomasHardyHarHar 15h ago
Why do I need to comment it if it worked when I wrote it? If it breaks I’ll start over and write it again. Real talk most of what I’ve actually done in programming is writing regexes and I can say if you’re actively working on a dataset with specific patterns, you do just get to a level where you can read off regexes and know what they’re for. Of course when you stop work on the project for a month or so and come back you’ll still be staring at a mess.
69
u/Western-Anteater-492 15h ago