English lad currently a C#/Java/VueJs/JavaScript/TypeScript engineer.
Extra dribbling can be found at https://codeheir.com
Portfolio found at https://lukegarrigan.com
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.
That's necessary almost always because even the best written code can NEVER express its programmer's intentions.
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:
Clean code is simple and direct. Clean code reads like well-written prose. Clean code never obscures the designer's intent but rather is full of crisp abstractions and straightforward lines of control.
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.
So I now refactor my code to be as obvious as possible.
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.
...that style of documenting isn’t something I would do in my context.
And that's fine. I don't expect my take to work for everyone, everywhere, every time (unlike Robert Martin). I've yet to personally encounter someone who tried it and didn't benefit, but I've also yet to encounter a majority of programmers. ;)
I am curious whether you do TDD. Writing tests to express intent and check the code meets it is something done in my context.
Of course! Testing and CI is critical to our workflow. However, I've also found that testing, by nature, can replicate none of the benefits of intent-commenting.
In my experience, the best code is...
Clean (like I said, I do use many of Martin's principles),
Self-commenting,
Intent-commented (living inline specification),
Tested (good coverage),
Documented (not the same as commenting),
Reviewed.
In all my years of coding, I've never found any one of those items to be replaceable by any combination of the others.
Of course...
YMMV, and
If you're not working as part of a team, it may be hard to impossible to observe the negative impact(s) omitting one of the above might be causing. (e.g. you may not need to write a spec; you keep it all in your head...until you have another developer.)
Clean code is simple and direct. Clean code reads like well-written prose. Clean code never obscures the designer's intent but rather is full of crisp abstractions and straightforward lines of control.
There is an unresolvable paradox here. I agree that if you want to read code like prose, it must consist of abstractions. Otherwise the nitty-gritty details would have to be exposed. But remember, abstractions likely take you away from the "direct" and "straightforward".
It's one more level in your mental stack to balance. The question lingers in your head, ok, what does it actually do in this case?
Often, abstractions can't be made "crisp", they are rather leaky.
Abstractions (aka how to partition concepts, where to draw lines) are hard to get right the first time. You need a good few iterations on them to begin with.
Even a good partitioning of concepts can be ruined later, when a new kind of edge-case needs to be handled. A tiny detail changes, the whole design needs to be revised. In reality, the tiny edge-case is often addressed at a place it doesn't really belong, making the nice prose lie.
Not complaining, just noting. Don't be shy of exposing details if that makes sense. Start to abstract one you see a pattern recur 3-5 times and have a good grasp on the various edge cases. Always be wary.
A good quote to live by when it comes to commenting and writing clear code comes from, I belive, a programmer by the name of John Woods. While it originates from the early 90s it's still a creed I live by:
“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.”
Code cannot express things external to code, such as - implicit assumptions about input data, performance considerations, all the background theory and extensive research put into the resulting optimised algorithm, experimental results (such as performance measurements) taken into account, and so on.
I believe in the very opposite approach - Literate Programming. You must have more comments than code, because code is the easy part, all the background thought trail is hard and must be recorded. No way you'll put it in your variable names.
The problem is that even if you write perfectly you have to consider different people reading your code as well and what you find clear I might find confusing and vice versa. I comment, not for me or people that read code like me, but for people that read code differently.
Basically it's like explaining things that I know is not general knowledge or common practise. Like I would do when writing any text.
It's like When Max Thunberg, a friend of mine, is to read my code. Well, not really, just wrote that sentence to demonstrate that while I and people around me know who I meant I had to comment on who Max is to clarify for others. The same could be true when, as an example, I'd call an API. If I used an unconventional way to save memory I'd also comment on why I didn't follow conventions.
Another reason is to speed up on boarding of junior developers or just developers coming from other languages.
Yet another reason could be to help none coders, like customers, understand the code.
Lastly I have dyslexia and for me comments makes code more readable even when I don't read them simply by breaking up the code, giving me visual anchors.
So,while I agree with the notion that comments are failures to express ourself clearly enough through code I also believe that to be an impossible task.
This could be a nice code challenge, to take a piece of commented code and refactoring it without comments in a way that's more clear and then discuss the different solutions.
This is such a valuable view! Inclusiveness is so important for designers, but we developers forget it. Everybody must be as good as us, our code should tell everything. But someone with dyslexia, or someone not proficient in English, or even beginners will have a hard time if we do not take them into consideration
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
We're a place where coders share, stay up-to-date and grow their careers.
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.
And that's fine. I don't expect my take to work for everyone, everywhere, every time (unlike Robert Martin). I've yet to personally encounter someone who tried it and didn't benefit, but I've also yet to encounter a majority of programmers. ;)
Of course! Testing and CI is critical to our workflow. However, I've also found that testing, by nature, can replicate none of the benefits of intent-commenting.
In my experience, the best code is...
In all my years of coding, I've never found any one of those items to be replaceable by any combination of the others.
Of course...
YMMV, and
If you're not working as part of a team, it may be hard to impossible to observe the negative impact(s) omitting one of the above might be causing. (e.g. you may not need to write a spec; you keep it all in your head...until you have another developer.)
that's very well said. thanks.
There is an unresolvable paradox here. I agree that if you want to read code like prose, it must consist of abstractions. Otherwise the nitty-gritty details would have to be exposed. But remember, abstractions likely take you away from the "direct" and "straightforward".
It's one more level in your mental stack to balance. The question lingers in your head, ok, what does it actually do in this case?
Often, abstractions can't be made "crisp", they are rather leaky.
Abstractions (aka how to partition concepts, where to draw lines) are hard to get right the first time. You need a good few iterations on them to begin with.
Even a good partitioning of concepts can be ruined later, when a new kind of edge-case needs to be handled. A tiny detail changes, the whole design needs to be revised. In reality, the tiny edge-case is often addressed at a place it doesn't really belong, making the nice prose lie.
Not complaining, just noting. Don't be shy of exposing details if that makes sense. Start to abstract one you see a pattern recur 3-5 times and have a good grasp on the various edge cases. Always be wary.
Code has a nasty little tendency to be paradoxical, doesn't it? XD
"Clean coding" principles always require careful thought; Clean, DRY, SOLID Spaghetti is still spaghetti. :P
A good quote to live by when it comes to commenting and writing clear code comes from, I belive, a programmer by the name of John Woods. While it originates from the early 90s it's still a creed I live by:
Code cannot express things external to code, such as - implicit assumptions about input data, performance considerations, all the background theory and extensive research put into the resulting optimised algorithm, experimental results (such as performance measurements) taken into account, and so on.
I believe in the very opposite approach - Literate Programming. You must have more comments than code, because code is the easy part, all the background thought trail is hard and must be recorded. No way you'll put it in your variable names.
The problem is that even if you write perfectly you have to consider different people reading your code as well and what you find clear I might find confusing and vice versa. I comment, not for me or people that read code like me, but for people that read code differently.
Basically it's like explaining things that I know is not general knowledge or common practise. Like I would do when writing any text.
It's like When Max Thunberg, a friend of mine, is to read my code. Well, not really, just wrote that sentence to demonstrate that while I and people around me know who I meant I had to comment on who Max is to clarify for others. The same could be true when, as an example, I'd call an API. If I used an unconventional way to save memory I'd also comment on why I didn't follow conventions.
Another reason is to speed up on boarding of junior developers or just developers coming from other languages.
Yet another reason could be to help none coders, like customers, understand the code.
Lastly I have dyslexia and for me comments makes code more readable even when I don't read them simply by breaking up the code, giving me visual anchors.
So,while I agree with the notion that comments are failures to express ourself clearly enough through code I also believe that to be an impossible task.
This could be a nice code challenge, to take a piece of commented code and refactoring it without comments in a way that's more clear and then discuss the different solutions.
This is such a valuable view! Inclusiveness is so important for designers, but we developers forget it. Everybody must be as good as us, our code should tell everything. But someone with dyslexia, or someone not proficient in English, or even beginners will have a hard time if we do not take them into consideration