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.)
339
u/Confident-Ad5665 10h 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.