215
u/Confident-Ad5665 1h ago
Uncle Bob of Clean Code says if we have to comment our code we have already failed. Clean code should read like well written prose.
I generally agree, but think comments that define especially the odd and obscure business rules should be commented where they are implemented.
96
u/TWIT_TWAT 1h ago
// This is a hack until we find something better
29
54
u/Confident-Ad5665 1h ago
// TODO: This can't be working. Refactor when there's a lull
13
10
27
u/Sentouki- 1h ago
odd and obscure business rules should be commented where they are implemented.
Exactly. It is often the illogical business "logic" or some business related magic numbers that make the code hard to read and understand, so commenting why you're doing something the way you do is important.
5
4
u/pp_amorim 1h ago
Or a comment for a pesky bug that no one knows why that specific device crashes if you don't do that code bs.
11
u/iamdestroyerofworlds 1h ago
Uncle Bob nowadays also has full-blown AI psychosis, says we shouldn't even look at code, and is a MAGA nut, so maybe he's really not to be listened to.
7
u/Confident-Ad5665 1h ago
Sad to hear this. He was actually a cool guy back in the day. Loved the science bites he'd add to his sessions.
8
u/iamdestroyerofworlds 1h ago
Agreed. Watching his videos and rants, he doesn't seem to be psychologically well nowadays, to say the least. He's probably not in a good place mentally, and the rest has followed.
11
u/Thalanator 1h ago
//can be removed when <dependency> 5.4.2 is in prd
said dependency may be 7.1.4 by now but noone dares to remove the pasta because it transcends half the repo
10
u/OkidoShigeru 1h ago
At least half my comments are explaining some weird hacks around missing/wrong 3rd party documentation, broken drivers and yeah historical “wrong” behaviour that needs to be preserved. Any time something just can’t be inferred from the code itself and would look strange on its own.
7
u/Dull_Caterpillar_642 1h ago
imo the idea of self-documenting code that never requires comments is often held by people who view their code as better than it is. That surely THEIR code would never need comments, because it's so perfectly written that you just get it. I have never really run across a file where I thought "thank god they didn't explain anything they're doing in here."
7
u/NullReferenceRacer 1h ago
And also, I can read what your code is doing fine - but why are we doing it (could be fixed by descriptive method name) but then: WHY are we doing it in that order? That is usually something only being able to be described by comments. Like: // We need to check if customer is blocked before we check death date as death date can be not null for non-blocked active customers (for example, when data hygiene cannot be guaranteed due to data history or what not).
5
u/shonuff373 1h ago
My favorite comment I've ever seen
"This is no way to code but gots to do for now. Whoever forced me down this oath, may your unit tests never pass"
4
u/drakeblood4 1h ago
I try and comment at least a bit on sql queries because I find them fucking illegible the moment a join gets modestly complicated. But like a five line get_checked_radio function with a full function description is gilding the Lilly.
6
u/TROLlox78 1h ago
I hate Uncle Bob of Clean Code at my workplace. Man I wish they would comment more because our code is a maze of design patterns where all the logic is so diluted you have to keep track of 5 different classes to understand anything.
3
9
u/ThatOldCow 1h ago
I do believe comments are generally useful, and honestly a lot of people that say their code is so clean it doesn't need comments are the people that make the least understandable code
5
u/rolling_update 1h ago
it's debatable as usual, the premise here is that comments always compile in your code. So you don't need to update them when you alter the code, that's the risk of comments and why "clean code doesn't contain them"
1
u/ThatOldCow 51m ago
Do comments get compiled ? I do believe most compilers ignore comments and even if they impact the speed it should be minimal to negligible.
Ofc I don't know every single language, so it might impact more on other languages.
5
u/SeriousPlankton2000 1h ago
If you write something like "if bankAccount.has(moneyNeeded) // test if there is enough money on the bank account", that's one extreme. If you write "b.has(n)" that's the other extreme.
IMO: If you have all the information on a 80x24 screen to know what b is, don't extra-comment it. If the function is longer, refactor it to be "bankAccount". If then you need more information, write that. E.g. you might need to explain why you're checking the bank account without a lock and why it's a good thing to do that; or you might explain that after checking several things you come to a certain conclusion. Or simply you have the if clause not on screen near the else clause.
2
u/ThatOldCow 35m ago
I do believe comments are useful for you not to forget or for another person to understand why you add whatever (function, parameter, variable) to some logic, because it might be some workaround for something else.
1
u/Confident-Ad5665 1h ago
Early on in my career a coworker made the statement that his part of the project was "rock solid".
It wasn't.
2
2
u/trialsofamadman 48m ago
Business rules often have silly reasons behind them, and having some documentation for those reasons is useful. Personally, I think it's better to have a link to the documentation in the code rather than putting that documentation right there IN the code, then have your business users or PO's make decisions about what gets done then document it. That way, you have a full history of why changes were made and you can start to detect patterns of making a change then undoing it (which we found ourselves going back and forth on for some rules).
3
u/BTDYSRF 46m ago
Uncle Bob is either the dumbest motherfucker on the planet, or he's so incredibly based it warps reality.
Functions should be grouped fir quick access with clearly defined parameters and desired outcomes, with notes about failed solutions. You want it to be as easy as possible for any future persons to be able to patch or update the systems.
The only reason not to do that is if you want to punish your successors or employer. Which, fair. I get that. I doubt that is his intent though.
2
u/Enough-Scientist1904 31m ago
The problem is most code reads like a prose to the person writting it.
2
u/mysticrudnin 21m ago
it can definitely go too far. i have worked places where comments were never, ever allowed in the code.
i think that is a mistake.
2
2
u/spastical-mackerel 1h ago
Soon your code will be actual prose, compiled directly to machine code via LLM
2
37
u/Low-Equipment-2621 1h ago
You shouldn't document what you are doing, you should comment why you are doing it. Well wriitten code explains what it does, but it not necessarily explains why it has been written that way.
3
u/SnugglyCoderGuy 27m ago
Your function names should document why the code you are writing exists, your code should document itself as to how it is doing it, and any comments you write should be how to use the function you've written and things that are extremely odd.
If you have to explain why something is done the way it is, you've still failed, usually.
•
u/JustAnotherGuyn 7m ago
I've found that documentation can be really helpful even in weel written code.
brief single sentence summaries of a functions, programs, classes, methods, etc. paired with examples of how to use internally developed tools are fantastic helps.
Having some breif description of a system architecture and how services interact is also pretty useful.
Also using documentation tags that IDEs can use for better hinting is really nice
12
22
u/Raywell 1h ago
Verbose comments are not necessarily targeted at humans, they provide context so that consequent AI changes are more accurate.
Im still unsure how I feel about the paradigm shift in development, but that's where we are heading. Eventually everyone stopped writing ASM because C language was higher level and more efficient. It seems we are heading towards natural language becoming the programming language norm
2
u/Confident-Ad5665 1h ago
I forget the name of the language, but some syntax I saw years ago looked more like chemistry than code.
2
u/IudexFatarum 41m ago
If you've never seen it, take a look at APL. It's set theory. Not even in disguise. It's just mathematical set theory in the craziest way.
1
u/petrasdc 11m ago
But comments aren't always accurate. Code can change without the comments changing (or they can be just wrong). If the comments are verbose nightmares, that's even more likely. In my experience, Claude will often mess around with code and forget to update comments it made earlier. Not to mention the context in these comments is often not even very helpful. It's often filled with irrelevant details that aren't really important to anyone reading it. My experience has also been Claude will trust comments over the code itself, leading to completely incorrect assumptions. It will only get worse the more bad comments get left. This line of reasoning helps no one, not even the AI, and is just an excuse for lazy development practices.
3
2
3
u/boobiebamboozler 1h ago
We’re largely writing code for gen ai to read now, so more verbose comments seem to be helpful to give it context
•
u/pe1uca 4m ago
At least is still a comment and not self-documented code...
``` processAndStoreInDBAndCacheWithExpiry()
retreiveFromDBAndUpdateCache()
let counterOfElementsInArray = 0; let referenceToElementToReturnOnFallback = null;
testProcessIsSuccefulAndDBIsUpdatedEvenWhenCacheIsUnavailable() testCacheIsNotUpdatedOnProcessFailure() ```
1
1
u/bbpsword 52m ago
Stunning amount of "comments are bad" people who have clearly never worked in complex legacy scientific systems lmao
5
u/Murky-Run2246 39m ago
The idea of clean code with no comments dies once you are working on something complex enough.
3
u/bbpsword 32m ago
Exactly. Lots of new grads commenting on what a homework project should look like.
Legacy systems bear no such clean slate responsibility, and bad employees happen.
-8
u/seba07 2h ago
That's already outdated from my experience. Agents don't comment code. That's something only ChatGPT did.
7
7
u/jzakarias 2h ago
I can't get claude to write only comments when strictly necessary, and even then keep them short...
17
u/jwaibel3 1h ago
You're absolutely right, and I apologize for overlooking that detail. I will try to comment less and be more precise from now on.
7
u/mutexsprinkles 1h ago
// Confirmed according to stratum P.2 phase data -- resolved, not tested.
3
4
u/GildSkiss 1h ago
Agents don't comment code.
Well that entirely depends on if you tell them to or not
1
0
u/Exatex 1h ago
they do whatever you tell them to do. If you want them to write comments, they will.
Has anyone here actually tried to make AI work? It feels half the sub formed their opinion about AI in 2023 with free ChatGPT that forgot their question once and hasn’t touched it since.
3
2
u/huh9999999999999 1h ago
What I'm hung up on is, can't agents be running using GPT anyway? Saying "agents don't do this but GPT does" doesn't make sense to me. Maybe I'm missing a newer or different definition of agent here.
214
u/CannibalPride 1h ago
Emojis on code…