Hacker News new | past | comments | ask | show | jobs | submit login

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.


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"} ??


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.


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.


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


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.


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


In fewer words: comment why, not what.


I prefer:

Comment why, not how.


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




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: