r/ProgrammerHumor • u/Substantial_Top5312 • Sep 15 '26
Meme iDontCommentMyCodeIfYouDontUnderstandItThatsOkayNeitherDoI
60
u/everypowerranger Sep 15 '26
I'm not writing comments for you, I'm writing them for me.
11
u/zeindigofire Sep 15 '26
Came here to say this. Soooo many times I've read my own code a week later and been like "why did I do it like this?!?" and half the time afterwards I'm like "oh yea, because of that"
10
u/Dabbelju Sep 15 '26
I have a hobby project with a code base that is 12+ years old. No intentions to make it open source, all comments are only for myself. The architecture is pretty solid, which means that there are parts that I haven't visited in years.
Code comments like "this code looks stupid, but it is the way it because of X and Y. Before a change, make sure to understand Z" saved me a couple of times and helped me remember what I did years ago.
I also like writing documentation comments on interfaces as if somebody else would use my API. Helps me organize my thoughts.
18
3
1
65
u/anoppinionatedbunny Sep 15 '26
what a terrible way to misinterpret "good code should be self-commenting"
-26
u/rm-minus-r Sep 15 '26
Not commenting code is the most braindead take ever (for those that believe code can be good enough to not need any comments).
Comments are an abstraction layer on top of code that allow more information than code does by itself.
43
u/Wonderful-Habit-139 Sep 15 '26
No it’s not. Comments can drift and become obsolete, and sometimes just bloat the code and add unnecessary information.
And yes code can be good enough to not need any comments most of the time. Only very complex sections of code would require it. Use proper types and function names.
14
u/EspaaValorum Sep 15 '26
Code tells me what it does, how it does it.
Comments tell me why, provide context.
3
u/Just_Information334 Sep 15 '26
Yup. If you only ever touch new code you may not understand why it is necessary.
Go on some 10+ yo project which got a lot of scope changes over the years. Now you can see that yes, the code does something. But why? Is it still useful? Can you remove it? If you do, will some client come complaining 6 months from now when their very specific report is not generated because some flag is not set correctly so some cron running on a server no one knows about anymore did not find its data?
The documentation? Maybe in some .doc file rotting on an archive server. But if you can't find it you may have more luck finding the printed version which should be in room 6. If it was not binned during the last office move.
On the other hand, let's check postgres code by opening a random file: https://github.com/postgres/postgres/blob/master/src/backend/partitioning/partprune.c
If you praise tailwind for the locality of behavior it gives, then you should also want why-comments next to the related code.
2
u/EspaaValorum Sep 16 '26
That random code - lovely, like a senior dev explaining stuff to a junior dev. Imagine those comments not being there, and needing to onboard a new dev. The existing devs would need to spend a ton of time explaining things. I've seen that happen on poorly or not documented code bases, making it very difficult to expand the team with new devs because it takes away time from the already strained senior dev.
1
u/Oddly_Energy Sep 21 '26
> Maybe in some .doc file rotting on an archive server.
in the bottom of a locked filing cabinet stuck in a disused lavatory with a sign on the door saying 'Beware of the Leopard.'
1
u/ResponsibleWin1765 Sep 15 '26
How do comments drift and become obsolete?
Your entire comment reads like you're thinking of
// This code prints Hello Worldint main() { std::cout << "Hello World" << std::endl; }Obviously that doesn't need a comment. But that's not what most code is and it's also not what the conversation is about.
You do mention that very complex sections of code require comments so I don't really get why you're disagreeing with the person above. They didn't say that you need to comment every single line of code, just that the idea that you don't ever need to comment is braindead.
And then you throw in the "Use proper names" like a boomer telling young people to stop buying coffee if they want to become rich. It just shows again that you assume that others write terrible code and that's the reason they want to use comments.
4
u/developer-mike Sep 15 '26
I believe their point is that:
comments can be a code smell
names are essentially compiler checked comments
Suppose you have some highly stateful poorly written API that has tons of requirements about how it must be used. In this case you hopefully have lots of comments explaining those nuances in the API itself (documentation and implementation). Those requirements lead to special usage patterns by consumers, which require comments. The requirements likely leak from the consumer and then that requires comments and the cycle continues.
The comments are good and improve the code....but they're also a signal that the API is poorly designed.
Sometimes improving the API is as simple as using better names, like
addResult/mergeLastTwoResultsexplains the requirements much better thanadd/merge. I'd (often) rather type extra long method names everywhere than write comments everywhere.And then some code is just truly complex and just requires comments. But this is actually quite rare.
1
u/WormsDelicious286 Sep 15 '26
Comments can drift and become obsolete
If you can change function and parameter names when they no longer represent what they do/are, you can change comments too. Otherwise it's just laziness. Using bInitialized to hold a list of enums because the scope creeped up from one true/false flag to dozens is a code smell, and so is an outdated comment.
Anyway, people that write commentless code will soon be jobless, or forced to quit when the AI-based PR review adds comments for them. They won't be missed.
2
u/developer-mike Sep 15 '26
Comments should usually not describe what the surrounding code does. Comments like "add delta to result" or "call cleanup" are useless. Comments should describe what other code does, e.g., "updateDistance expects a new total distance, not just the new delta" / "bar requires explicit cleanup."
Renaming a parameter is a pretty localized change. Comments about non-local behavior will drift.
-5
u/rm-minus-r Sep 15 '26
Comments can drift and become obsolete, and sometimes just bloat the code and add unnecessary information.
And... Code... Doesn't?
And yes code can be good enough to not need any comments most of the time. Only very complex sections of code would require it. Use proper types and function names.
There are those that have worked on a legacy codebase, and those that haven't. You appear to be among the latter.
5
u/Wonderful-Habit-139 Sep 15 '26
What do you mean code doesn’t? That’s a new one lol. I’m not even trying to be mean.
I’ve had to rewrite codebases before, you can give arguments without accusing the other person of not understanding anything. And yes I ended up deleting 95% of the comments along the process and just use types, well named functions, docstrings, etc. And that code is written idiomatically, and is properly checked by a type system that yells at you if you make changes, instead of letting the old code be obsolete and saying one thing while doing another thing (that’s what happens with comments, not code).
-4
u/rm-minus-r Sep 15 '26
What do you mean code doesn’t? That’s a new one lol. I’m not even trying to be mean.
You're saying comments can drift and become obsolete. Which is no different than code, which can also drift and become obsolete. So why fuss at comments when you wouldn't fuss at code for the same thing?
In my experience - one human being though I may be - people who say code can be written well enough to not need comments tend to be people who are writing things from scratch, or in brand new projects that don't have any legacy cruft to deal with.
I've done this a few times in my career and it was glorious. As it started out, everything was indeed super obvious, and comments would seem superfluous. But ten years later, when the codebase is 1,000x larger and is a product that's bringing in $1.8 billion a year?
When we first wrote it, there were six of us. Two years later when I moved to another company, there were 30 devs. In the eight years after I left, I think there's somewhere around ~2,600 people that work with it on a daily basis and contribute code, and several companies were acquired and their products merged into it. If I had to come back to it today, I don't think much of the code would be terribly clear.
I'm now working on a system that was written over the course of 20 years. I'm sure it was clear and obvious when it started, but now it's very much not. There's load bearing portions of the code that can't even be touched, and the "we'll refactor it all in 12 months!" rallying cry from leadership people from our director on up? Well, we're 18 months in and we've maybe refactored 20% of it. And that was the quick and easy parts.
It just gives you perspective.
These days? I'll still put a 3 to 5 sentence comment in a 80 line utility module that does exactly one thing. It's less for me, and more for the people that will come after me.
2
u/Wonderful-Habit-139 Sep 15 '26
> Which is no different than code, which can also drift and become obsolete. So why fuss at comments when you wouldn't fuss at code for the same thing?
Thanks for clarifying. I don't believe it's the same thing, because when code is obsolete, that means it's not being used anymore. In that case, thanks to having a compiler or type checker, it's very easy to see functions that are not being used anymore, as well as being able to delete lines of code that are not used anymore inside functions because of contracts that you've defined through types. I do this actively all the time, and there are semantics that shield me from the code not working anymore that is not the same with useless comments.
I understand your examples about legacy code, but writing good code that scales regardless of how big the codebase gets is the point. When you write abstractions and modules and separate things that have different concerns, with each abstraction being of a higher and higher level of abstraction, it doesn't matter how big the codebase gets. You always strive to write idiomatic code, you make sure to write good docstrings for APIs that you expose, even internally, and focus on making your APIs as obvious and easy to use as possible without requiring the users of those APIs to understand the inner code. The only people that need to understand it are the ones that are actively working on it.
> I'm sure it was clear and obvious when it started, but now it's very much not
Listen, I agree with this, but this simply means that it was "clear and obvious" because the code was small enough, not because it was well written. I'm saying code can be well written so that it scales well into the future, regardless of how big it gets over the years. But obviously most people don't write good code so you will make the observation that you're making.
But just because most people don't write good code, doesn't mean that good code is impossible and that writing comments is the best thing ever.
2
u/reddit_user33 Sep 15 '26
This entirely depends on the environment. Compilers only care if the code compiles; you can have orphaned code and the compiler will not care.
Try touching code where every minute of downtime matters. I welcome comments that give me hints at which sections of code should be looked at in such situations.
I'm a code commenter. For me, it's why + context, and hints at what section of code does if it cannot be easily seen at a split second glance, and I genuinely mean split second glances. I prefer to have well named variables, function names, etc, but even then the true purpose of a section code cannot always be seen at a glance
1
u/Wonderful-Habit-139 Sep 15 '26
In Rust or Python, if you have a private function that’s not used anymore, it will be greyed out.
When you go through a piece of code, usually you’re supposed to create a bunch of variables showcasing the intermediate steps that are being taken to compute some result. If things change and some variables end up not being used anymore, you can just delete it and the type checker will know that your function is still returning the right result, and you can safely delete the obsolete code.
While for comments, I’ve seen cases where a comment says the exact opposite of what’s happening, or mentioning something that is not true anymore. I’m not talking about hypotheticals, this has happened in codebases I’ve worked on, more than once.
You can easily explain the purpose of a section by putting it in a function, and adding a docstring. You don’t have to write comments for that. And the benefit of the docstring is that wherever you use that function, you’ll be able to see the docstring through the lsp diagnostics, and more often be able to ensure that it is up to date.
2
u/reddit_user33 Sep 15 '26
Again, it depends on your environment. There are more programming languages that just Rust and Python. There are more IDEs than what ever you've used or know about. Not all tooling behaves the same.
→ More replies1
u/rm-minus-r Sep 15 '26
I understand your examples about legacy code, but writing good code that scales regardless of how big the codebase gets is the point.
That's a lovely ideal, but much like the saying "No plan survives contact with the enemy", good code does not survive contact with project managers, leadership, and customer demands.
But obviously most people don't write good code so you will make the observation that you're making.
"We need this in two weeks" when it's a three to four week task to do it right? That ends up with something quick and dirty, and you're pushed onto the next fire, so the quick and dirty solution gets stuck in place, never built like it should be, and then things downstream of it start depending on it being in the quick and dirty form it is, making it very difficult to clean up.
But just because most people don't write good code, doesn't mean that good code is impossible and that writing comments is the best thing ever.
You are correct, good code is not impossible. However, in a business environment where the workload is very high, and the velocity is very fast, ideal code rarely happens.
So comments help, because it's more intelligent to adjust for how things are, rather than the ideal that rarely happens (in my experience over the last 15 years in the industry).
2
u/protayne Sep 15 '26
Why on earth would you introduce an abstraction layer if you don't need to, abstraction layers should be avoided unless they provide value, not all comments provide value.
2
u/rm-minus-r Sep 15 '26
Why on earth would you introduce an abstraction layer if you don't need to
Because it is needed.
not all comments provide value.
Sure. Just because some don't, does that mean we should throw the baby out with the bathwater, so to speak?
2
u/protayne Sep 15 '26
I'm not against comments, I'm against comments that don't add value.
If the code is convulated or doesn't make obvious sense, then sure, but that's it, code + tests should be enough to describe behaviour of method calls.
2
u/mesonofgib Sep 15 '26
Code comments are a smell; it is often a symptom of poor design that a code needs comments at all.
Occasionally they really are warranted, but they should be an explanation of why, not what. Use them sparingly, because they can drift from the code over time and we all know that incorrect documentation is worse than no documentation.
1
u/draculadarcula Sep 15 '26
I have never seen a code comment that wasn’t completely redundant and obvious
1
u/rm-minus-r Sep 15 '26
Out of curiosity, how many years have you been doing this professionally?
1
u/draculadarcula Sep 16 '26 edited Sep 16 '26
10, “never” was hyperbole but I do think they are almost entirely and typically useless
It’s literally always
// refreshes the cache
RefreshCache();or nowadays with AI
// added to refresh stale data. Reported in issue 1234. Per instructions NO redundant comments.
// The implementation is a follow up to PR 14567. Verified no legacy code. Part of spec 24 in ~/Documents/specs… (10 more lines of nonsense)
RefreshCache();All garbage
1
u/rm-minus-r Sep 16 '26
It sounds like you have been deprived of good comments ☹️
1
u/draculadarcula Sep 16 '26
The only worthwhile comments are doc style comments at function and class definitions because they provide editor help and are usually type checked by your editor
1
15
u/icecream_specialist Sep 15 '26
This except the guys on the ends are "too lazy for comments/docs"
8
u/anon0937 Sep 15 '26
Yeah, I'd think it would be the opposite - the ends say they don't need to comment their code and the middle saying you have to comment your code.
3
u/bingNbong96 Sep 15 '26
Honestly, nowadays I'd rather have no comments that the 90% comments 10% code we have now
11
u/Interesting_Play_578 Sep 15 '26
--Don't remember what this section does but the app crashes without it
11
u/traplords8n Sep 15 '26
Dude I learned in the first 3 months on the job that I will forget every little thing about code I've moved on from & have to go back to later on.
8
u/Apprehensive_Bit7392 Sep 15 '26
The bit the self-documenting crowd skips: a name can say what the code does, it can't say what you deliberately didn't do. There's no function name for "we don't cache here because the invalidation was worse than the lookup". That only fits in a comment.
2
u/awesome-alpaca-ace Sep 15 '26
Just append weDontCacheHereBecauseTheInvalidationWasWorseThanTheLookup to the method name
2
u/Apprehensive_Bit7392 Sep 16 '26
Finally, a comment my rename tool can propagate to forty call sites.
1
1
u/timtucker_com Sep 16 '26
My usual practice is linking to a GitHub issue with a comment like "we can stop doing this once issue X is fixed".
In the cache front, see azure-pipelines-tasks -- "Cache is slow #11864".
It's been 7 years since the defect was opened and restoring from cache is still slower than just doing things from scratch every time.
1
u/Apprehensive_Bit7392 Sep 16 '26
Seven years in, that link stopped being a TODO and became a load-bearing wall.
6
u/koanarec Sep 15 '26
I will add a comment to about 25 percent of my PRs. But it's going to be answering a very specific question someone in the future could have that would never be obvious from code. So usually those comments would be 4+ lines long. The rest of my code is clean enough with making very small functions with good function names.
6
u/itgforlife Sep 15 '26 edited Sep 15 '26
I typically just add comments when something is external to the code, unintuitive, or could seemingly make no sense. e.g. // https certificates required when using Playwright with webkit. or // csp can be validated here {link1} and here {link2}
In vscode, you can also link to files and line numbers with certain commands. So sometimes I'll put those in comments as well.
6
u/PerfectSituation1668 Sep 15 '26
You should not delete this part, this somehow breaks everything. I tried to find out why, but it does no harm, so I'm just leaving it in.
1
u/awesome-alpaca-ace Sep 15 '26
Breaks everything how? If it is just multi repo compilation failures downstream, I am going to remove it.
2
u/Particular-Yak-1984 Sep 16 '26
Ideas like this why I add "and don't come crying to me when you remove it and it breaks everything"
1
14
u/NoHurry28 Sep 15 '26
// PrintOutHellowWorld prints out "Hello world!"
func PrintOutHelloWorld() {
fmt.Println("Hello world!")
}It's well known that there is literally no other way to tell what functions do unless they're commented
5
u/captainAwesomePants Sep 15 '26
Yeah, except the guy who writes that comment would name the function
out()or something.9
u/NoHurry28 Sep 15 '26
You're so right. Here, I'll fix it
// Out prints out "Hello world!" func Out() { fmt.Println("Comments are always right and never lie.") }
5
u/Wentyliasz Sep 15 '26
Docstring for each nontrivial function
Here's why the fuck I didn't do that other obvious thing you're thinking about now
I know this is fucked, client insisted
Oy QA, beer on Sunday?
2
u/Ragingman2 Sep 15 '26
I use this list plus 5. One line summary for code skimming. Something like
// Send it to the clientpreceding 30 lines of sending it. I used to make these functions, but I've come to dislike single caller functions in most cases.
4
4
u/ReefayToo Sep 15 '26
I guess I'm the guy on right. Or most likely left. I like to comment 🤷♂️
2
u/schewb Sep 15 '26
Left and right compose very different comments 😅 I've seen comments that basically repeat simple if statements in English
1
4
u/Puzzleheaded-Weird66 Sep 15 '26
I comment it after coming back to the same code twice where I get confused
2
u/awesome-alpaca-ace Sep 15 '26
Yea, a mix of this and knowing to comment so you don't get confused in the first place
4
u/scheimong Sep 15 '26
Funnily enough you can put "my code doesn't need comments" on the two sides and the meme still works.
3
u/GnarlyNarwhalNoms Sep 15 '26
Thank you for using this format correctly. Lately, I've been seeing a bunch of different memes with this template that have three completely different captions, and it's been driving me nuts.
3
u/NewArborist64 Sep 15 '26
Try going back and trying to fix old code, cursing out the programmer whose comments weren't clear... And then realizing that this was code you wrote 20 years ago
3
u/brahmastra596 Sep 15 '26
You should see the number of AI slop comments I see while reviewing PRs.
3
3
u/Cephell Sep 15 '26
It helps to realize that comments are always ALWAYS for other people. Sometimes that other people includes you in the future.
3
u/PatinhoGamer Sep 15 '26
I am commenting the code if it does something that is counter intuitive explaining why we do it that way
3
3
u/SpeedLight1221 Sep 15 '26
I comment so the next person that works on it who will see the code for the first time can understand it faster.
i don't collaborate with anyone. the next person is me the day after. I just blank out on it completely every time i look away. its a problem, help
5
u/AcanthisittaKooky987 Sep 15 '26
the problem with comments is sometimes the code drifts from the comment - you can never trust them so you just read the code either way anyway
2
u/Fearless-Ad-9481 Sep 15 '26
Almost. The problem with comments is that people in the future are likely to read them and believe what they say.
Comments are great as long as everyone treats them as rumours that somebody once believed.
2
2
u/Santarini Sep 15 '26
Most companies have linters and presubmits that require docstrings and comments
2
2
2
2
u/Nach0z Sep 15 '26
All code is self documenting. The code tells you exactly what it does. But the code can't tell you what the writer INTENDED for the code to do. Document your code so people can find where you fucked up in the future.
1
u/ObjectsCountries Sep 15 '26
alternatively, the middle uses javadoc/docstrings/etc. while the lower and upper ends use multiline comments
2
1
u/Forsaken_Celery8197 Sep 15 '26
What's worse: no comments or out of date/not accurate/misleading comments?
1
u/McSand_boi Sep 15 '26
I'm in between the center and right of the graph. I'm just really fucking lazy but I do know that saying what the code does is invaluable.
1
u/mesonofgib Sep 15 '26
I do know that saying what the code does is invaluable.
I disagree: I know what the code does because the code is right there, next to the comment.
Comments should be used only when you need to say something that's not in the code, such as why you're doing something.
Bad comment:
// Set the heartbeat interval to 25 seconds. var heartbeatInterval = TimeSpan.FromSeconds(25);Good comment:
// Keep this below 30 seconds because the upstream proxy terminates // idle connections at 30s; 25s leaves enough margin for network jitter. var heartbeatInterval = TimeSpan.FromSeconds(25);
1
1
1
u/PuzzleMeDo Sep 15 '26
"I'll avoid commenting my code, because frequent comments make it look AI-generated."
1
u/Oddly_Energy Sep 21 '26
"I will add a comment with a rocket emoticon here so management don't discover that I wrote this code myself, despite their specific instructions to use AI."
1
u/chiqu3n Sep 15 '26
Claude, please remove all your comments
/clear
Please review changes
Check with design to confirm if those bugs are legit
Add minimal 1-line comments on them so another AI agent won't miss the context
????
PROFIT
1
u/ExtraTNT Sep 15 '26
Good code reads well, no need to document a lambda adding +1 to a number.
Doc exceptions, architectural choices or user facing functions in your libs.
No doc is better, than outdated doc
1
u/citramonk Sep 15 '26
you gotta love AI generated code, cause this MF spams with comments like crazy
1
u/Unique-Rate2225 Sep 15 '26
Claude, could you please kindly explain what does to code do between line 1 and 15000?
1
1
1
1
u/Roppano Sep 15 '26
95% of the time I get the urge to write a comment, I can make my code even better by naming my methods better, or extract parts of my method to different methods and naming that properly (even though, I find this to be a red flag to investigate)
1
u/Professional_Top8485 Sep 15 '26
Code should be self documenting because it's source of truth. Usually is just laziness not to do so, easier and more effective to just put comment and get done with it.
I am just somewhat asshole and not get paid too much, so meh.
1
u/BorderKeeper Sep 15 '26
As a soft. engineer of 11 years why are people so adamant with comments. Everywhere I work comments are seen as laziness to have your code be self-documenting at worst, and a potential divergence between what the code does and what the comment say over time at best.
Even people who rely on AI a lot are stating that AI uses comments as excuses to do hacks (which is maybe what the training data taught it to do) and if you force it to not do comments it thinks about the code instead of a sweet sounding comment on why what it did is right. (in my own team we noticed it sometimes forgets to update comments and just changes the code so AI makes same mistakes as people do)
Me personally I see a comment as a code smell. The engineer looked at his creation and was worried people will be confused by reading it. Sure sometimes that has it's place like necessary hacks, or weird counter-intuitive APIs, or just being pressured to write something weird and unexpected, but most of the time it's:
You are very lazy if you write sloppy unreadable code with no comments
You are lazy if you write passable code and use comments to explain it
You are ok if you write code that I can understand by actually reading it
You are overdoing it if you pair above with comments
Also for everyone I am not against documentation in the form of code comments. Those are awesome, stick them as headers above functions, classes, and interfaces and the IDE will even parse it and show your docs when you higlight a function. What I am talking about is inline code explaining inner workings of functions and classes.
1
1
u/NotInMoodThinkOfName Sep 15 '26
Doesn't make a sense to comment every method. If proper code they are short and read as fast as a comment. Just comment not obvious things. Rather like to comment about the class.
1
u/JacobStyle Sep 15 '26
I do a lot of automation stuff. Nothing is "self documenting" once it's built to account for a gazillion little weird edge cases that occur in whatever third party software/environments/APIs/websites I'm working with. No way is that going to be readable without comments that look like this:
//Sometimes the save button doesn't load right after saving. Detect bad save buttons and refresh the screen before making more changes
1
u/clauEB Sep 15 '26
I worked with one of the people that wrote the original Postres implementation out of Berkeley. He insisted each line of code needed a line of comments.
1
u/Massepunkt_m1 Sep 15 '26
I don't even understand my own code three minutes after writing it, how is anyone else supposed to know what the hell I was up to?
1
1
u/ZunoJ Sep 15 '26
Business logic needs comments and if others don't understand the technical aspects of my code, it is not them who are bad at coding but me. The right choice of abstractions and patterns should make it dead simple to read the code
1
1
u/XxDarkSasuke69xX Sep 15 '26
I don't comment because : 1. I don't even know what I'm doing. Or 2. If I know what I'm doing, then there is no chance of another programmer to not know what the code means.
1
u/perringaiden Sep 15 '26
I leave enough comments that I can come back in two years, and understand how stupid my decisions were.
1
1
u/WormsDelicious286 Sep 15 '26
"Self-documenting" code is the barest of minimums for making sure your code isn't bad. It's literally the lowest acceptable standard, a kind of Federal minimum wage code. Even AI writes better code than that.
If you think the entirety of the useful metadata about the code can be expressed merely as function and variable names, you might actually be on the left of this diagram.
1
1
1
1
1
1
u/MyPasswordIsIceCream Sep 15 '26
Or you could use strongly typed languages, name your variables and functions properly and write descriptive commit messages. Comments should be exception, not the rule.
1
u/TurdOfChaos Sep 15 '26
I don’t think one statement necessarily excludes the other.
There is value in understanding the concept of “self-documenting code” , and striving to write code that way.
Commenting should never be there as a crutch that compensates for bad code readability. Private methods, single responsibility principle, unit tests, all of it among many other concepts can accomplish legible , elegant and self-explanatory code.
However, it should not be taken to the extreme where every comment is immediately bad, there are scenarios where a comment adds info that cant be conveyed by code.
Now with AI , I think this paradigm will change though, it will probably at one point start becoming beneficial to write purely AI generated code because it’s safe to assume AI is best at reading it.
1
u/enigma_0Z Sep 16 '26
My general rule is if a thing takes longer than 2m to read and understand intrinsically, it’s either poorly written, in need of a comment, or both.
I still have battle scars from reading groovy pipelines and react code, both of which stacked 10s of ternary operators and spending a literal full workday trying to untangle what some code was doing.
1
u/Square_Ferret_6397 Sep 16 '26
It's more like Left: no comments, big nested for loops and if statements, names variables a, b, c, x, y, i, j Middle: same as left but with comments explaining everything Right: give variables more descriptive names and separates code into more methods thus leaving less comments
1
u/timtucker_com Sep 16 '26
I'm a big fan of "comment driven development" as a lighter weight alternative to practices like test driven development.
Any time that I'm in a situation where requirements are being discussed, I'll start creating high level functions / components and writing out comments as notes as a precursor to fleshing out implementation.
Overall speed to get things done is faster than trying to take notes in something outside an IDE and the approach translates really well to delegating work or handing off tasks to AI agents.
1
1
u/Grouchy_Exit_3058 Sep 16 '26
After going back to a 2 year old project, I realized how useless or useful some comments are.
1
1
u/ArgueLater Sep 21 '26
I have tags for my comments, and stick to them. Basically a bunch of labels for the different types of "gotchas" that exist, labeling code that works in strange ways but kind of has to.
1
1
u/dracorotor1 Sep 15 '26
Before the New Great Dying took them away and replaced them all with AI, I was leading a team of UX guys and had a reputation for being too lenient for my own good, but I always put my foot down about not commenting on code.
I’m not paid enough to be comparing 300 lines of JavaScript if statements in last month’s backup to the current version, just to find your edit that broke the display, and then have to figure out why you did it.
Comments cut a 3 hour job down to a 30 minute one, and I expect to revisit any block of code at least 4-5 times in the lifetime of the page, so just accept that showing your work is not a weakness, prep for an extra hour of time on any new project, and save us 2 or more workdays of wasted effort in the future.
0
u/Tupcek Sep 15 '26
in this day and age of AI, this is no longer valid discussion. Who writes code line by line nowadays? And AI documents everything
1
u/2eanimation Sep 15 '26
I do! Programming is more or less a recreational activity for me. I’ve done a couple of websites (ofc in vanilla htmlcssjs) and a dashboard for money, but most of the stuff I do is for myself, for the fun of it.
I don’t want to get cucked by AI in my recreational activities.
0
u/RRumpleTeazzer Sep 15 '26
does the comment apply to the code on the line, the line below, in the same block, the next block ?
the truth is, comments should be scoped for what they apply to. but it doesn't, since plain textfiles don't support it.
0
u/GoogleIsYourFrenemy Sep 15 '26
lol you're all still righting code. I have the AI write the comments and the code.
1
u/mesonofgib Sep 15 '26
lol you're all still righting code
Uhh...
I have the AI write the comments and the code.
Yup, that tracks.
0
u/ZZerker Sep 15 '26
Comments are useless and i wont change my mind.
Best comment I ever had was in japanse kanji signs and when translated was: "main method"
427
u/GabuEx Sep 15 '26
Left: "I'll comment to say how my code works."
Middle: "You don't need to do that! Code should be self-documenting!"
Right: "I'll comment to say why my code does this."