I disagree with "Naming itself is not reliable enough to communicate our intent no matter how clever the name seems".
Combined with parameter/return types I believe the signature of a function can fully convey the intent of the function, at least to the point of it being used correctly.
At times I'd argue the name itself is sufficient. Consider a simple function like radiansToDegrees, it's hard to mistake the intent of this function.
No, interpreting radians that way is just wrong. We have to assume that the people working on our project have at least taken a passing interest in the domain and would understand the commonly used, and perhaps uncommonly used terms. Trying to communicate to somebody that knows nothing about what's going on is a waste of time.
Your comment also causes confusion. Does this mean I can't use this function where it doesn't involve UI? Is this conversion somehow special to the values that a user might input. You've done the opposite of what a comment should do: you've added unclarity where before there was none.
"Assuming a passing interest in the domain" is good, assuming everyone in your team has a common set of vocabulary is more problematic. For the specific example you gave, I admit my interpretation as temperature was contrived.
I frequently work with people for whom english is not their first language, and I have found that describing even "obvious" function names has been very helpful.
Also agreed that the one liner I gave was not helpful by itself; to match the form of the article, my comment would have fit in the "Intent" line.
In reflecting on your feedback, I realized that I mostly use "why" comments inside function bodies whenever I'm doing something weird. So I guess unless your function is doing something weird, "why" comments matter less.
There is certainly a reason why "Naming" remains one of the hardest problems in Computer Science. Absolutely better function signature are very helpful but not enough. Also, depending on the type of application you are developing, "sufficient" may not be the level of clarity to strive for.
Saying something is "not enough" is unfortunately not a strong enough justification for adding comments to all functions. Though many functions do need comments, a large percentage (maybe not more than half), of the functions I've seen on projedts simply don't need to be commented.
Always keep in mind that comments interfere with refactoring. It's easy to break up and splity apart the code of a function, but it's time consuming and error prone to do the same for comments.
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.
I disagree with "Naming itself is not reliable enough to communicate our intent no matter how clever the name seems".
Combined with parameter/return types I believe the signature of a function can fully convey the intent of the function, at least to the point of it being used correctly.
At times I'd argue the name itself is sufficient. Consider a simple function like
radiansToDegrees, it's hard to mistake the intent of this function.One thing I've noticed over time is that 'simple' is extremely context dependent.
To take your example, if I didn't happen to know what 'radians' meant, I could interpret your function as having something to do with temperature.
Beyond that... I think "communicating our intent" is not the same as "communicating what the code does". E.g.
Captures intent (I need degrees for the ui) whereas the un-commented version just explains the 'function'.
No, interpreting radians that way is just wrong. We have to assume that the people working on our project have at least taken a passing interest in the domain and would understand the commonly used, and perhaps uncommonly used terms. Trying to communicate to somebody that knows nothing about what's going on is a waste of time.
Your comment also causes confusion. Does this mean I can't use this function where it doesn't involve UI? Is this conversion somehow special to the values that a user might input. You've done the opposite of what a comment should do: you've added unclarity where before there was none.
"Assuming a passing interest in the domain" is good, assuming everyone in your team has a common set of vocabulary is more problematic. For the specific example you gave, I admit my interpretation as temperature was contrived.
I frequently work with people for whom english is not their first language, and I have found that describing even "obvious" function names has been very helpful.
Also agreed that the one liner I gave was not helpful by itself; to match the form of the article, my comment would have fit in the "Intent" line.
In reflecting on your feedback, I realized that I mostly use "why" comments inside function bodies whenever I'm doing something weird. So I guess unless your function is doing something weird, "why" comments matter less.
There is certainly a reason why "Naming" remains one of the hardest problems in Computer Science. Absolutely better function signature are very helpful but not enough. Also, depending on the type of application you are developing, "sufficient" may not be the level of clarity to strive for.
Saying something is "not enough" is unfortunately not a strong enough justification for adding comments to all functions. Though many functions do need comments, a large percentage (maybe not more than half), of the functions I've seen on projedts simply don't need to be commented.
Always keep in mind that comments interfere with refactoring. It's easy to break up and splity apart the code of a function, but it's time consuming and error prone to do the same for comments.