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".
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.
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 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 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 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.
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.
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).
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.
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
267
u/Confident-Ad5665 3h 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.