The moment in my career when I had enough experience to have my own understanding of what makes code maintainable and organized and didn't have to just kind of rely on the opinions of a couple popular other people was a glorious day. It's not like their theories are all bad, it's just they're prescriptive to their personal style and there are actually a lot of perfectly good ways to organize code.
Btw., critiquing: "This is how he cleans the code in 2024: Original version on the left; the cleaned-up version on the right:" -- that doesn't render side-by-side on my mobile and I wish every web author would consider labeling/naming content boxes instead; and would reference that, like good books are doing it.
This is yet another very good critique, but it's long past time that we stop paying attention to Uncle Bob.
Not only are his ideas about how to write software patently bad, but he is willfully obtuse when asked to provide nuance or discuss trade-offs. John Ousterhout's dialog with him, published as "A Philosophy of Software Design vs Clean Code" gave him every opportunity to think critically about his own suggestions and he just doubles down.
I had Code Complete (uh, I think?) and stuff like using early returns and consistency with conditional clauses (negative or positive first) was an interesting way of looking at software. I don't think I ever read the full book though.
> Am I right? I think I am; but you may disagree. That's OK.
The blog author says these are okay, but I think these are a bad cop-out too. If it's okay to disagree, what you're saying is fundamentally worthless. If what you're saying has merit, would improve code and the lives of people working on it, then it's worth working until people see the merits of what you're saying.
If you're writing a whole book about how people should do something different but then you waffle off, I'm definitely not going to spend effort reading the book.
> assertTrue(b.compareTo(a) == 1); // b < a
I think there are definitely places where comments are useful (providing domain context, definitions, documenting invariants on fields, separating code sections and communicating general intent, etc).
I think reading code is a critical skill though, and a lot of people use comments as a way to avoid that, and I do think there are issues when you do a soft-duplication of the code in the comment. For instance, if the above code had `== 0` would anyone notice?
The ascii diagram thing seems bad to me. I'd be absolutely terrified of having to modify that diagram if something changed (did they use some external program to generate it then copy and paste? what program? can it round trip? Or did they spend hours fiddling with spacing to make everything line up?) People look at code on various width screens, and it's going to wrap and stop being a diagram and instead become a paragraph of gibberish.
The fact that programming languages don't support actual diagrams in comments is a language failure, but I think practically you should stick to prose and if you need diagrams, store it externally as an image or maybe mermaid in a markdown document or something.
And I disagree on commented out code. I've seen too many MRs containing every experiment the author did on the way to producing their final draft, commented out. Commenting out MRs are a way to avoid committing to keeping or deleting code.
Commented out code rots - nobody's going to touch the commented out code when refactoring. At best people will ignore it, and it'll just be noise that gets in the way. At worst people will read it, missing the context from when it was actually functional, maybe getting confused about how various constructs work now based on code from a different era.
The code is already in git if you really need to get it back (as a bonus, with all associated context), there's no point to keeping it around as a comment too.
The moment in my career when I had enough experience to have my own understanding of what makes code maintainable and organized and didn't have to just kind of rely on the opinions of a couple popular other people was a glorious day. It's not like their theories are all bad, it's just they're prescriptive to their personal style and there are actually a lot of perfectly good ways to organize code.
fyi, the split code view on your site with two different versions on the left and right is completely broken on mobile
Btw., critiquing: "This is how he cleans the code in 2024: Original version on the left; the cleaned-up version on the right:" -- that doesn't render side-by-side on my mobile and I wish every web author would consider labeling/naming content boxes instead; and would reference that, like good books are doing it.
his books exist mainly to help sell consulting gigs
there was a whole tribe of 90s oh-oh pundits hustling
This is yet another very good critique, but it's long past time that we stop paying attention to Uncle Bob.
Not only are his ideas about how to write software patently bad, but he is willfully obtuse when asked to provide nuance or discuss trade-offs. John Ousterhout's dialog with him, published as "A Philosophy of Software Design vs Clean Code" gave him every opportunity to think critically about his own suggestions and he just doubles down.
https://github.com/johnousterhout/aposd-vs-clean-code/blob/m...
He's just trolling us at this point.
I had Code Complete (uh, I think?) and stuff like using early returns and consistency with conditional clauses (negative or positive first) was an interesting way of looking at software. I don't think I ever read the full book though.
> Am I right? I think I am; but you may disagree. That's OK.
The blog author says these are okay, but I think these are a bad cop-out too. If it's okay to disagree, what you're saying is fundamentally worthless. If what you're saying has merit, would improve code and the lives of people working on it, then it's worth working until people see the merits of what you're saying.
If you're writing a whole book about how people should do something different but then you waffle off, I'm definitely not going to spend effort reading the book.
> assertTrue(b.compareTo(a) == 1); // b < a
I think there are definitely places where comments are useful (providing domain context, definitions, documenting invariants on fields, separating code sections and communicating general intent, etc).
I think reading code is a critical skill though, and a lot of people use comments as a way to avoid that, and I do think there are issues when you do a soft-duplication of the code in the comment. For instance, if the above code had `== 0` would anyone notice?
The ascii diagram thing seems bad to me. I'd be absolutely terrified of having to modify that diagram if something changed (did they use some external program to generate it then copy and paste? what program? can it round trip? Or did they spend hours fiddling with spacing to make everything line up?) People look at code on various width screens, and it's going to wrap and stop being a diagram and instead become a paragraph of gibberish.
The fact that programming languages don't support actual diagrams in comments is a language failure, but I think practically you should stick to prose and if you need diagrams, store it externally as an image or maybe mermaid in a markdown document or something.
And I disagree on commented out code. I've seen too many MRs containing every experiment the author did on the way to producing their final draft, commented out. Commenting out MRs are a way to avoid committing to keeping or deleting code.
Commented out code rots - nobody's going to touch the commented out code when refactoring. At best people will ignore it, and it'll just be noise that gets in the way. At worst people will read it, missing the context from when it was actually functional, maybe getting confused about how various constructs work now based on code from a different era.
The code is already in git if you really need to get it back (as a bonus, with all associated context), there's no point to keeping it around as a comment too.