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