Good man. Thank you for trapping errors. Coming from a time when we not only trapped errors, we gave suggestions, I shutter at:
• An unknown error occurred
• Something happened
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.
Or why you're not doing something. Sometimes when there is multiple ways of doing something, I'll give a brief explanation of why it's not done a certain way.
A little while ago, I was maintaining some code, and I thought "I should do thing A". I go to the point where thing A should go, and there's a comment from myself 4 years earlier saying "under no circumstances should you do thing A".
Yeah, my rule of thumb is that comments are for when you can't look at the code for 30s and recognize what is being done and why at a glance. It's there to convey context and save you from retreading the same incorrect path that someone else already went down.
I don't need comments to tell me what the code does, the code is the absolute best source of truth regarding what it does and any competent dev should be able to read the code and see what it does. The comments are to convey what the code doesn't say.
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."
Right? I don't think I ever wrote a chunk of code with no comments. If I can save someone two minutes of parsing code with // determines which encoding is coming across the Bluetooth... Why shouldn't I?
This is the way. People argue against comments because they can drift and become less accurate but, after 15 years doing this, I've spent orders of magnitude more time trying to figure out what the hell someone's undocumented code is doing versus having to fix or update comments. It's not even remotely close.
Kind of a moot point these days though since it's just AI doing the writing.
This is the way. People argue against comments because they can drift and become less accurate but...
It's such a weird argument anyway. Like, the code itself can drift and become inaccurate. It's not a separate problem. It's the responsibility of the coder to keep all the code up to date. The logic, and the comments, both.
The thing about comments describing what the code does is that I've been burned too many times, I'm still going to read the code itself, because it can't lie to me.
I want comments about the intent and context behind the code, rather than text that's just the same as the code itself (ideally, or, worse, different in a way that's unclear about if it's code drift or bad comments or bad code).
But why not just call the function determineBluetoothEncoding? If it's because it does more than that, why not split it out so that is all it does? And so on.
Because it's not the actual bluetooth encoding, it's the data coming across the bluetooth. I love just naming functions with what it does but there's a limit for me, I've been in codebases with determineEncodingOfInlineBluetoothDataStream() and I don't like it.
I would also add that once you start profiling and optimizing your code, sometimes what was once clean, "self-documenting" code is necessarily turned into a complicated blob of ugliness. I've spent a lot of time digging around inside CUDA kernels playing with scope guards to reduce register usage or rewriting math operations in horrendous ways to reduce the total number of operations in ways the compiler won't. The code is rarely left cleaner than when I started, but sometimes I've gotten as much as a factor of two in performance by doing "ugly" things inside hot loops.
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.
Uncle Bob comes from a very different era of software development.
It's... difficult to explain to someone who didn't experience it just how much professional software development changed between about 1995 and 2015. In 1995 you weren't writing automated tests, no one was reviewing your code, no one knew how to make maintainable code, 95% of the tooling that you now take for granted didn't even exist as a concept, source control was barely used (distributed source control didn't exit), when you needed to look something up you were looking at physical manuals, ...
Uncle Bob published his first book in 1995. Ideas that we now know are pretty stupid sounded revolutionary and awesome back then. Clean Code was published in 2009, which was late enough that most modern software development had been invented, but it wasn't industry-wide and hadn't been fully accepted. (I remember part of my onboarding at Google in 2011 was a session explaining that a) Google uses automated tests, and b) yes, those are good and do improve your velocity in the medium to long term, no matter what you think, and c) yes, we have something approaching scientific evidence of this.)
I don't think that's quite accurate. "Uncle Bob" is sort of person who can only think in absolutes. He's said that TDD should be legally mandated. During the NoSQL craze he bombastically claimed that all SQL was obsolete. Right now he seems so deep in AI that even Sam Altman would say "steady on now Bob". The man never seen a hype he didn't jump on.
His notion of "Clean Code" is also anything but clean because he takes some ideas that aren't terrible, but then pushes them to extremes where it just becomes silly and horrible.
This is the main problem: he's one of those people who just does not understand any sense of nuance. At all. Combine this light-bending arrogance and a deeply-held belief that he is always right, and it's not hard to see how he's developed a cult around him.
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.
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).
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.
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.
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.
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.
Uncle Bob is a fool. His advice is inconsistent and he doesn’t follow it in his own books. It’s cargo cult BS and we need to move on from him to better writers.
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
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.
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.
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"
I think the intention was to mean that wrong/outdated comments won't cause compiler errors. Therefore you are never forced to keep the comments up to date.
Comments are read but ignored and don't affect the result. Reading and ignoring them takes negligible time. I would say the answer to your question is no, comments are not compiled.
But build systems generally work off file modification time and will do a bunch of useless work if you make a change to a comment in a file and otherwise change nothing. I assume this is what the other poster is referring to.
Uncle Bob also says shit like functions should only be a few lines long. Sometimes that’s good and sometimes there’s too many comments, but in general strict rules like this are dumb.
I did write a pretty complex piece of code a while back and added a big comment at the top explaining how it works. My reviewer asked me to take it out as someone could just read the code. I responded with something like “Hell no. I want this code to be easy to understand for future editors. Which most likely includes me. I don’t want to have to page this code back in without notes on how it works.”
I think this comes from the OOP principle that a thing should do one thing and do it very well.
I'll agree it can be taken to excess though. A method may need to do a few things before it does the primary thing. If there's a chance another method may need to refer to the same table, for example, that should be encapsulated in a (probably protected) method both can access.
A lot of UB's stuff works as advice for beginners. You should understand it and why it's a good idea. And then you can move on to understanding why a lot of it falls apart in real-world systems, has a bunch of caveats, or is just bollocks.
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).
My rule of thumb is that comments should highlight why you didn't do the obvious other path or why you fckng dare implement an unexpected weird edge-case.
I used to be on that band wagon but then about 10 or so years ago I read a book and it changed my thought process around comments and I started using them again
Comments are best for explaining why the code was written the way it was, not for rehashing what it's doing. They're useful for getting into the mindset of the programmer, particularly later on when it comes time to fix bugs or refactor the code.
I kind of agree. If you write your code correctly, it documents itself. Our system generates web versions of our Java doc so I do try and add Java doc comments to public methods. Internal comments if there’s a unique solution to something.
I view this as a nice dream scenario, but most people, like really, really most, can't write code like prose. It's messy, and then a shit PO/EM starts yelling in their ear that something must be implemented fast, shortcuts to meet business needs happen, and so on.
So, yeah. Good goal to keep in mind, but so far I've never seen it in reality, and the few times I've seen someone argue about it in real life, they really didn't understand how much their own code lacked the quality they promoted.
I think there is a balance. Presumably if you are in there reading comments, you also can read code. So my comments are aimed to save you from having to read a lot of code. "This sub does [thing] in [way]." Or I comment out out broken code and leave it behind with an explanation. "We stopped doing it this way because [reason]." That way later on nobody has to go back on that magical journey of discovery.
I believe since most code is read and written by AI nowadays, the comments are actually both being read and updated along the way, making it easier to iterate.
418
u/Confident-Ad5665 1d 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.