DEV Community

Discussion on: Removing Comments

codemouse92 profile image
Jason C. McDonald

...I can't even be sure that's what the code is doing.

Ergo, the intent comment. What is my intention? Why am I writing that code there? If you can't be sure that's correct, then perhaps something is wrong.

I know we can parse semantics here, but I'm not talking theory. The ROI on the commenting standard I describe is actually observable within my own company.

So, yes, you might be describing what you intend for it to be doing. And, yes, there are rare cases where a comment is pointless. But the problem with examples like the above is that they're oversimplified. In the real world, those two little lines of code appear within the context of hundreds or thousands of lines of code, and hundreds of functions with potentially similar names. In practice, the benefit of those intent comments becomes apparent when you begin using it in a real-world context.

Thread Thread
jasonlotito profile image
Jason Lotito

So how do I verify your intent without you and automatically?

Thread Thread
codemouse92 profile image
Jason C. McDonald • Edited on do I verify your intent with you...

The same as how you verify my code without me. Read it.

...and automatically...

The same as how you verify my code automatically. On a large scope, either that's what happens in the tests, or it isn't. On a smaller scope, you don't.

Beyond this, I really doubt this conversation is going to be productive. I know intent-comments work because I actually use them in production. But, I have learned that there are camps who believe that comments are a waste of time, and who will continue to believe they're a waste of time regardless of what I have to say about it. ;) So, I think we'd better agree-to-disagree at this point.