Superpower
Let's face it, us developers live in a very strange world. Explain what you do to 95% of the population and they'll likely gl...
Some comments have been hidden by the post's author - find out more
For further actions, you may consider blocking this person and/or reporting abuse
I don't know. Uncle Bob has some good things to say (e.g. SOLID), but he's also spawned a few bad ideas, too, like this...
To me, that alone shows that Robert Martin has forgotten what it's like to jump cold into someone else's code, especially code using languages, tools, or concepts he isn't familiar with. And anytime someone is so lost in their own expertise, they forget what it's like to NOT be an expert, I have to call literally everything else they have to say into question.
In my experience, comments should generally express the WHY (intent) of the code. That's necessary quite often because even the best written code can NEVER express its programmer's intentions. The WHAT is obvious, but the WHY is often inexpressible in machine logic.
To Comment Or Not To Comment?
Jason C. McDonald ・ Jan 20 '19
Besides that, even an extreme absolutist "best practice" declarations like "comments are always failures" show a contemptible sort of arrogance. That sort of statement reads as "My expertise is so vast, it accounts for every conceivable situation and exception. I have nothing more to learn."
Even following his doctrine religiously cannot yield perfect code. There is no "one size fits all" solution.
Clean, DRY, SOLID Spaghetti
Jason C. McDonald ・ Jul 24 '18
But then, I've always found that Robert Martin just tends to be unable to distinguish his opinion from objective fact, and he's given to believing his own press releases. Ego precludes trustworthiness in my experience, and on that basis, I recommend looking to less egotistical sources for programming practice. Even if Martin coined some of these otherwise brilliant concepts, I'd rather they be (re)taught by someone who vetted them in practicality and humility.
I guess this is just opinion-based, I'll be honest I partly agree with his statement. I would much rather jump into code and see intent expressed through variable/function/class names. In the book, he actually goes on to talk about the appropriate times to use comments.
I don't agree with this, if done properly code can absolutely express the programmers intent, pretty much the entire purpose of learning to write clean code. What Grady Booch said springs to mind:
Well, I think it's a point worth discussing (maybe elsewhere? It's bound to get long). All I know is, intent-commenting has always yielded vast returns for me and my company.
It has reduced "onboarding time", especially for beginners.
It highlights logic errors, which are caught sooner.
It reduces code review time.
It reduces the time spent picking up one's own older code by at least half, usually more IME.
None of the above precludes clean coding principles (aside from comments). You never need a comment to see what the code is doing by itself or in direct context...only why it's there, in the grand, fully-abstracted picture.
It may come down to one's definition of "intent," but based on clear and measurable results, clearly Uncle Bob missed something.
And that's my main point. Robert Martin stated an absolute as if it were utterly impossible for him to be wrong in any case, and yet I can point to many cases where he literally was. The main issue is, Martin regularly confuses his opinion with objective fact.
That sort of absolutism is why I trust nothing coming directly from Martin; only once it has been vetted by programmers who combine experience with humility, will I consider it something of merit. (I learned many Clean Code principles this way, and I follow them.)
Well I do kinda find the absolutist style a little jarring myself. Yet I am largely skeptical about anything that I cannot related to person experience. I am also aware that I have some of the same tendencies to declare things as absolutes based on my own personal experiences.
In the case of comments, I believe that there is/was a school of thinking that comments are good, so more is better, and maximum is best, so folks would slap a giant comment in a big banner over every tiny method. I literally had a college supervisor who did that himself and taught it as best practice. Comments would say obvious stuff so you stopped reading them and often they were out of date, misleading or vague.
This means that when I first read the book it was a lightbulb. It was literally telling me something my college supervisor did wasn't a good idea. I had kinda figured it out but I still would have said comments were mandatory as that was what I was taught.
It depends on the language, the task, the team, and the context what is appropriate. If I am writing for my main day job I aim to write brutally simple and obvious code. I spent a significant amount of time to reread my code and mentally explain it to an imaginary third person with no experience. I picked this up from joining a large team where we would have to do a show-and-tell of code we wrote that was a new feature. It was done in the large team to share knowledge on a global call. We tended to practice presenting before hand as it was embarrassing when someone was trying to talk about their code and it was a trains smash. Often someone in the audience would ask about a specific block of code and the presenter who recently wrote it would stumble to explaining it. When rehearsing whenever I would stumble I would refactor my code to rename classes, methods and variables. The renaming was always to better express the intent of the code.
Time permitting I always rehearse presenting my code as I read through it even if I never present it. As I do this I refactor my code to be as obvious as possible. Sometimes due to time or just complexity of the situation I cannot make the code clearer. So I slap a comment on it. This always feels like is a small defeat.
Well, and see, the commenting style I'm advocating (read the article I posted) doesn't conflict with this. It should always be obvious what your code is doing.
That's not what I mean by "intent". For example, the best clean code will show you that you're looping through all the entries in your "clients" dictionary and uppercasing the first letter of the name, but it may not be clear you are "correcting name capitalization issues"...or if said intent is obvious, it might not be so until you read and ponder 3-7 lines of code for a bit. That's wasted time.
(Pedantic Note: Yeeeeeees, the above example could be wrapped in a function called "fixNameCapIssues()"...I'm referring to sections of code that cannot be abstracted out. In practice, that's most.
Intent commenting is actually a living specification. You know that old rule about "don't code without a spec"? Put the spec in comment form, and code within.
I'm not the first to pioneer this. Donald Knuth created an earlier (and much clunkier) approach called Literate Programming.
If your comments simply describe what your code is doing, you should refactor so the code's function and purpose is obvious, but you should include a comment describing the language-agnostic intent of the logical section of code.
Make more sense?
(Read my article I posted earlier in thread about this for a more in-depth explanation, if that still doesn't make sense.)
Thanks for the link but that style of documenting isn’t something I would do in my context. I concede that If I joined your team I might discover that first over commenting and then removing the obvious comments might be optional in your context.
I am curious whether you do TDD. Writing tests to express intent and check the code meets it is something done in my context. That goes beyond self-documenting code. Code reviews expect a test suite as specification and that it is clean code with self documented intent.
I recently finished reading this book with some colleagues at work. The consensus opinion to come out of it is that you won't fully benefit unless you read the book critically. While 80% of the book is good advice, about 20% is controversial to downright bad advice. Plus, most of the book is grounded in quite outdated Java versions, some of it in dire need of an update (and largely irrelevant if you don't use Java).
If you're new to the idea of writing "clean code", you might not be able to recognize the 20% of bad advice. So if you do read this book, remember to take everything with a grain of salt; it's just one more perspective to keep in mind while writing code, not the definitive perspective.
This is exactly the point I was making earlier!
Robert Martin has a lot of good ideas, but his apparent ego prevents him from distinguishing between his opinion and provable reality.
I recommend developers learn clean coding from more trustworthy (less egotistical) authors, who have vetted these ideas in their own careers. I can never recommend a young developer read Robert Martin's work directly.
Amem to that. There are a lot of good ideas in his books. That's a fact. But distinguishing between the good and the bad advice is difficult when you are just starting to learn how to code.
I am not a big fan of commenting code, but sometimes it is required (but not always). Developers hardly read comments and most of the time it's just create noise.
Jason, I appreciate your
defensive approach to support code comments, but it's sounds to me an unnecessary conversation. It's all depends on agreement between team members whether to add comments and how much.
Can you please show some respect for Uncle Bob, based on his contributions,
To be honest, I don't think Jason was disrespectful in any way. He said Uncle Bob has a lot of great ideas. And pointing out that Uncle Bob has a gigantic ego which prevents him from distinguishing between his opinion and provable reality, is just the truth. He is still man with a lot of good ideas.
A video by Bob Martin delivered in Norfolk UK blew my mind. It starts off very strangely talking about human biological evolution. That seems very odd but stick with it. He then drops the bomb on what makes clean software architecture which is that everything must be a plugin to your business logic to keep it clean youtu.be/o_TH-Y78tt4
Oh god, this kills me, I'm from Norfolk! Such a brilliant speaker.
Wow, you beat me to it! I'm currently reading this book again and was planning on sharing the same sentiments on here soon 😂
Totally true though, this book is an invaluable resource. Highly recommend that anyone trying to get serious about porgramming takes the time to read it.
I love this quote!
Me too! I can't take credit for this one though, I did google around to see who originally said it, but failed miserably!
haha it's still a great quote!!! It might be John Woods.
While this may be completely true, it is completely forgetting the archenemy of every programmer, "The Deadline". When you are fighting the clock, and you have a choice, "Make it pretty, or make it work." This is typically when style goes out the window.
Yeah, unfortunately, this happens far too often. Especially when the product is new and the business wants to see results fast. It's in the developers' hands though, if they think it's going to take longer to make the code clean, maintainable, extendable then it's their responsibility to let the appropriate people know!
Nope. It is full of ill, destructive advice and OOP zealotry. Programmers who took this broken book too seriously are lost, and I personally will never want to have to work with any of them.
TL;DR: read the book, take it with a grain of salt, and try to take some of what Bob said into your daily thoughts about how some things are done.
As much as a like this book and it's commentary, this requires every developer that's ever touched a keyboard to live, eat, and breathe this ideology for it to be consistent. That doesn't mean that some of his suggestions can't be used, it's just that if you wanted this to be the holy Grail, it would really need to be executed perfectly.
That being said, look at CPPCoreGuidlines. Good standards based around a community and Bjarne. There are others like it for other languages.
Thank you for wrapping this up. I absolutely agree that every developer should read this book. The book gives really good advice on how to code and also what to express with code. In my personal opinion, Uncle Bob sometimes is a bit extremistic in making an argument though. He tends to explain a single aspect so sharply pointed, that it can be in the neighbourhood of "wrong" or contradicts his own arguments from other chapters. So when reading the book, each thing should be seen as a proposition how to work. Trying to understand what the author wants to express and how he came there is key to understanding the argument and bringing it to life under the own circumstances.
What I don't like is to see this book as the "Holy Bible of code", which indicates that every single letter has to be obeyed to. Not understanding the rationale but still adhering to the words as they were written can cause all different kinds of new classes of problem.
Before this book one should read the Pragmatic Programmer book, that is referenced several times in the Clean Code book, that now have a new edition to commemorate the 20th Anniversary from the first release.
Great article 😁
Thank you!
I like the book overall, but don't follow it blindly.
good recommendation and I am definitely gonna read this book, if you have good resources pdf of the book, I'd be glad if you send it to me, thanks by the way...
peace.
Absolutely true, this book has changed a lot about how I think and write code (excuse me, I meant TESTS)
I created a book list for software developer techread.dev
Definitely Clean Code is one of the best book.
Uncle Bob is one of the amazing software engineers alive today. Read as much of his work as possible. Some really good work.
Cannot agree more. Reading this book has changed forever how I see code
Exactly! It gives you a brand new perspective