No, that's not the point at all. The reason for CSI, for intent-commenting in general, is that intent cannot be reconstructed easily. You can figure out WHAT with any degree of conmpentency, but NOT why. This is a major reason we have so much bad code; we spend so much of our time trying to guess what we and other devs were intending, we waste hours trying to grok what a few comments could have helped us grok in minutes.
See, mind-reading is not part of the programmer's skill set. You cannot even necessarily remember your own intent six months after you wrote the code; if anything, you are intent-commenting for your own good.
Now, to clarify...that code you posted almost certainly doesn't appear alone in the code. You aren't facing a two-line block, you're facing a wall of code. What's the intent in context? Perhaps this is in a function that loads your contact list...
// We only want to see contacts we're subscribed to.
$contacts = $unsubscribedFilter->filter($contacts);
$contacts = $duplicateFilter->filter($contacts);
See? Now it's clear why the code is there. We can tell we're filtering out unsubscribed and duplicate contacts, but we now know why we're doing it - to filter the displayed results. Now if you are finding that you're seeing duplicates in the results, and go through, you might realize "oops, I'm storing the results in $contacts, but I should be storing them in $display! That's only easily grokked because of the intent content; ordinarily, you'd probably have looked right past it (code blindness is nothing to mess around with!)
And, for the record, I have encountered those sorts of situations in my own code for years.
Why do we only want to see contacts we're subscribed to? That comment just says what is being done, and I can't even be sure that's what the code is doing.
Well, you should refactor that, because as of right now, you have code that does something very specific (return a list of contacts you are subscribed to, not display that as the comment implies, btw). A better refactoring of that would be to do something like this:
function getContactsSubscribedTo($contacts) {
$contacts = $unsubscribedFilter->filter($contacts);
$contacts = $duplicateFilter->filter($contacts);
}
There. We've removed the unnecessary, confusing, "what's it doing" comment with a clearly defined and testable function.
...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.
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.
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.
No, that's not the point at all. The reason for CSI, for intent-commenting in general, is that intent cannot be reconstructed easily. You can figure out WHAT with any degree of conmpentency, but NOT why. This is a major reason we have so much bad code; we spend so much of our time trying to guess what we and other devs were intending, we waste hours trying to grok what a few comments could have helped us grok in minutes.
See, mind-reading is not part of the programmer's skill set. You cannot even necessarily remember your own intent six months after you wrote the code; if anything, you are intent-commenting for your own good.
Now, to clarify...that code you posted almost certainly doesn't appear alone in the code. You aren't facing a two-line block, you're facing a wall of code. What's the intent in context? Perhaps this is in a function that loads your contact list...
See? Now it's clear why the code is there. We can tell we're filtering out unsubscribed and duplicate contacts, but we now know why we're doing it - to filter the displayed results. Now if you are finding that you're seeing duplicates in the results, and go through, you might realize "oops, I'm storing the results in
$contacts, but I should be storing them in$display! That's only easily grokked because of the intent content; ordinarily, you'd probably have looked right past it (code blindness is nothing to mess around with!)And, for the record, I have encountered those sorts of situations in my own code for years.
Why do we only want to see contacts we're subscribed to? That comment just says what is being done, and I can't even be sure that's what the code is doing.
Well, you should refactor that, because as of right now, you have code that does something very specific (return a list of contacts you are subscribed to, not display that as the comment implies, btw). A better refactoring of that would be to do something like this:
There. We've removed the unnecessary, confusing, "what's it doing" comment with a clearly defined and testable function.
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.
So how do I verify your intent without you and automatically?
The same as how you verify my code without me. Read it.
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.