4 ms·

That's interesting, I had the complete opposite reaction to clean code. As a person that recommends this book, with full heart, to every developer, I'd like to

by Denzel 9y ago

That's interesting, I had the complete opposite reaction to clean code. As a person that recommends this book, with full heart, to every developer, I'd like to hear any details you could spare re: why you believe it's damaging? Maybe you can provide some examples of well-written codebases and why you believe they're such? And maybe you could comment on why you feel Clean Code's principles harm readability with some examples? I find it painful working with codebases that don't use most of the principles re: - Write code like good stories: Code should read like a story, methodically descending the call graph method by method; each working at one level of abstraction. For example, why is string manipulation littered all over this function that's supposed to be dealing with consolidating reports? Ugh. I like when one function stays at one level of abstraction - Factor out conditions into descriptive methods: I shouldn't have to sit and read through 5 logical operators, some arithmetic, and method calls in 1 'if' conditional, to understand why we're doing all this. Once again, this goes back to having your code read like a story. Factor it out into a descriptive function, so that I can understand at a glance and deep dive if necessary. - Comments are a failure: This applies 99.99% of the time. It's almost comical when someone leaves behind a comment that could be eliminated by factoring something out into a descriptive method call instead. There's a lot of other great stuff in Clean Code that I'm forgetting off the top of my head. (It's been awhile since I last looked over it.) I've come across very few code bases that are a literal pleasure to read. https://github.com/jekyll/jekyll https://github.com/jekyll/jekyll is one of the cleanest codebases that comes to mind immediately. And on the other side of the coin, https://github.com/kubernetes/kubernetes https://github.com/kubernetes/kubernetes is one of the dirtiest. If anyone wants more details/expansion, let me know and I'll reloop. (On my phone right now.)

Hasknewbie 9y ago
(Not parent) Having read both a long time ago, I also feel like Code Complete is the one to recommend: it covers more ground, is pragmatic, and more importantly most of its recommendations are based on studies, i.e. they come from empirical evidences. Clean Code compares poorly to this, in that it's just one guy's opinion. That doesn't necessarily mean Clean Code is a bad book, but since our work relies primarily on logic, I'd rather have arguments presented to me logically. Since both books cover pretty much the same ground, it makes more sense to recommend Code Complete.
chinhodado 9y ago
The problem with Clean Code is, just as the post you replied on said, it's very dogmatic. A problem I often see people who quote Clean Code do is that they take its principles to the extreme. An example is tons of tiny methods of 1-3 lines each. Sure splitting up methods is good practice but it's painful to read code where you continuously have to "go to definition". There is an article written about this by John Carmack here http://number-none.com/blow/john_carmack_on_inlined_code.html http://number-none.com/blow/john_carmack_on_inlined_code.htm... Another example is the "comment are a failure" mindset. Sure I don't need comments that say this code is doing an addition between two numbers, but a piece of code doing some complex business logic definitely benefits from a comment explaining what the hell it's doing. No amount of function-splitting and function-naming can replace such comments. Yet all too often people who read Clean Code treat comments as some sort of abominations that has to be avoided at all cost.
- Denzel 9y ago
  A dogmatic book does not make a dogmatic person. And if that's a "problem", then that's rather a problem with the person reading the book. Please provide examples of such codebases you're talking about. One justification of modularity is to hide details. Thus avoiding the need to "go to definition". If the tests pass and the name is descriptive, then you should understand the method without needing the details. For example, Jekyll's Site#process [1] provides a high-level overview of how the site is built. It reads like simple, plain, easy-to-understand English. Now, I've chosen to dive into Site#write [2]; it tells me that for each site file, we're going to write it out to its destination, as long as it's supposed to be regenerated. Awesome, that's easy to understand. Say I want to write another method that operates on all the site files. I don't need to know how Jekyll finds all the site files. Heck, they could be in specific directories... or it could pull configuration over the network... or they could be provided through command-line arguments. Who cares! I just use Site#each_site_file because it's an implementation detail. And yes, Jekyll provides little 1-3 line helper methods like Site#incremetal? [3] all over the place to codify conditionals. These are extremely helpful. On the other side of the coin, do you know what this conditional is for [4] in Kubernetes? I can't for the life of me understand its purpose without being forced to look into the details. It'd be much easier to read if it was extracted out into its own descriptive method such as activeMultiNodeInterface maybe? I don't know because I literally don't know the intention of that conditional. The original developer could've made their intention far more clear to subsequent developers had they extracted it out. I find your citation of Carmack underwhelming for two reasons: (1) he's writing to a very specific target audience -- game developers, and (2) he admits himself, "The whole point of modularity is to hide details, while I am advocating increased awareness of details." Carmack is in no way supporting the idea that "it's painful to read code where you continuously have to 'go to definition'". In fact, quite the opposite, he's advocating a very specific recommendation to a very specific type of developer working on a very specific type of project. Simple as that. You'd do best to provide some examples and empirical data supporting your assertions. [1]: https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site.rb#L69 https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site... [2]: https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site.rb#L208 https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site... [3]: https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site.rb#L347 https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site... [4]: https://github.com/kubernetes/kubernetes/blob/master/pkg/kubelet/network/kubenet/kubenet_linux.go#L203 https://github.com/kubernetes/kubernetes/blob/master/pkg/kub...

by Denzel 9y ago

Hasknewbie 9y ago

(Not parent) Having read both a long time ago, I also feel like Code Complete is the one to recommend: it covers more ground, is pragmatic, and more importantly most of its recommendations are based on studies, i.e. they come from empirical evidences. Clean Code compares poorly to this, in that it's just one guy's opinion. That doesn't necessarily mean Clean Code is a bad book, but since our work relies primarily on logic, I'd rather have arguments presented to me logically. Since both books cover pretty much the same ground, it makes more sense to recommend Code Complete.

chinhodado 9y ago

The problem with Clean Code is, just as the post you replied on said, it's very dogmatic. A problem I often see people who quote Clean Code do is that they take its principles to the extreme. An example is tons of tiny methods of 1-3 lines each. Sure splitting up methods is good practice but it's painful to read code where you continuously have to "go to definition". There is an article written about this by John Carmack here http://number-none.com/blow/john_carmack_on_inlined_code.html http://number-none.com/blow/john_carmack_on_inlined_code.htm... Another example is the "comment are a failure" mindset. Sure I don't need comments that say this code is doing an addition between two numbers, but a piece of code doing some complex business logic definitely benefits from a comment explaining what the hell it's doing. No amount of function-splitting and function-naming can replace such comments. Yet all too often people who read Clean Code treat comments as some sort of abominations that has to be avoided at all cost.

Denzel 9y ago
A dogmatic book does not make a dogmatic person. And if that's a "problem", then that's rather a problem with the person reading the book. Please provide examples of such codebases you're talking about. One justification of modularity is to hide details. Thus avoiding the need to "go to definition". If the tests pass and the name is descriptive, then you should understand the method without needing the details. For example, Jekyll's Site#process [1] provides a high-level overview of how the site is built. It reads like simple, plain, easy-to-understand English. Now, I've chosen to dive into Site#write [2]; it tells me that for each site file, we're going to write it out to its destination, as long as it's supposed to be regenerated. Awesome, that's easy to understand. Say I want to write another method that operates on all the site files. I don't need to know how Jekyll finds all the site files. Heck, they could be in specific directories... or it could pull configuration over the network... or they could be provided through command-line arguments. Who cares! I just use Site#each_site_file because it's an implementation detail. And yes, Jekyll provides little 1-3 line helper methods like Site#incremetal? [3] all over the place to codify conditionals. These are extremely helpful. On the other side of the coin, do you know what this conditional is for [4] in Kubernetes? I can't for the life of me understand its purpose without being forced to look into the details. It'd be much easier to read if it was extracted out into its own descriptive method such as activeMultiNodeInterface maybe? I don't know because I literally don't know the intention of that conditional. The original developer could've made their intention far more clear to subsequent developers had they extracted it out. I find your citation of Carmack underwhelming for two reasons: (1) he's writing to a very specific target audience -- game developers, and (2) he admits himself, "The whole point of modularity is to hide details, while I am advocating increased awareness of details." Carmack is in no way supporting the idea that "it's painful to read code where you continuously have to 'go to definition'". In fact, quite the opposite, he's advocating a very specific recommendation to a very specific type of developer working on a very specific type of project. Simple as that. You'd do best to provide some examples and empirical data supporting your assertions. [1]: https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site.rb#L69 https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site... [2]: https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site.rb#L208 https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site... [3]: https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site.rb#L347 https://github.com/jekyll/jekyll/blob/master/lib/jekyll/site... [4]: https://github.com/kubernetes/kubernetes/blob/master/pkg/kubelet/network/kubenet/kubenet_linux.go#L203 https://github.com/kubernetes/kubernetes/blob/master/pkg/kub...