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.)
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.