[FuzzyDunlop]

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.

[DannoHung]

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.

[le-manchester]

Not at all because programming languages like Ruby parameter names don't tell the full story:

if you have def find(name) what kind of type could be name? String "Steve"?? Symbol :Steve? Hash {:first => "Steve", :last => "Jobs"} ??

[aneisf]

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.

[paul-woolcock]

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.

[aneisf]

I'm not sure if it's Pythonic as I've never written Python. It's a habit I carried over from the .NET world, actually.

[mgurlitz]

Wouldn't the Pythonic thing be to only fail after you've tried, instead of validating your parameters in advance?

[agentultra]

Yes. It's easier to beg for forgiveness than to look before you leap. You just use your parameters regardless of types and let the exceptions fly.

[DeepDuh]

Is that really Pythonic? Isn't that just general best practice in programming?

[anthonyb]

In fewer words: comment why, not what.

[einhverfr]

I prefer:

Comment why, not how.

[einhverfr]

Exactly.

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 ;-)