I think it could be summarised as thus, in general terms:
You should never need to write a comment to explain what you're doing. If you feel you have to, rewrite the code until it doesn't need explaining in a comment.
# this method manipulates dimensions
def method_x(a, b, c, d)
# a is the width
# b is the height
# c is the depth
# d is a list of options
...
end
That could obviously be re-written as:
def manipulate_dimensions(width, height, depth, options)
...
end
However, it may very well be the case you have to explain why some code exists, or why it wasn't done another way:
def post_to_awkward_api(data)
# stupid.io doesn't accept HTTP Post params
# so we have to use a comma separated string
silly_string = data.join(',')
....
end
def bug_fix_workaround
# see http://stackoverflow.com/relevant-question/...
end
Not that my examples are amazing. But there'll always be the case where another developer (or even yourself) is not privy to the thought process that conceived a particular block of code.
We could probably resolve this aspect of the argument by teaching novices that a perfect/great/accurate/otherwise-superlative name(s) is better than almost any comment.
That just means that 'name' is a poor name for the parameter. Have 'first_name, last_name' or 'full_name' or 'names,' for example.
In addition, I think it's a good practice to get into to try and validate parameters at the top of any method. If the values don't fit your use for them, raise an exception.
That strikes me as very Pythonic attitude. If you're going to fail, fail early. But, I know Python way better than Ruby, so it might very well be a Ruby thing too.
Also I would say that not all comments are created equal. You comment your API's first, then implement/explain them with code, then describe why with more comments ;-)
You should never need to write a comment to explain what you're doing. If you feel you have to, rewrite the code until it doesn't need explaining in a comment.
That could obviously be re-written as: However, it may very well be the case you have to explain why some code exists, or why it wasn't done another way: Not that my examples are amazing. But there'll always be the case where another developer (or even yourself) is not privy to the thought process that conceived a particular block of code.