DEV Community

Discussion on: The ONE book every developer MUST read!

 
codemouse92 profile image
Jason C. McDonald • Edited

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

Thread Thread
 
simbo1905 profile image
Simon Massey

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.

Thread Thread
 
codemouse92 profile image
Jason C. McDonald • Edited

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

  1. YMMV, and

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

Thread Thread
 
simbo1905 profile image
Simon Massey

that's very well said. thanks.

Some comments have been hidden by the post's author - find out more