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