News for hackers. Stuff that matters.
Re:Thoughts on being a programmer by FuzzyDunlop on Tuesday August 14, 2012 @03:23PM (#4382657)
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.
Re:Thoughts on being a programmer by DannoHung on Tuesday August 14, 2012 @04:21PM (#4382896)
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.
Re:Thoughts on being a programmer by le-manchester on Tuesday August 14, 2012 @06:14PM (#4383340)
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"} ??

Re:Thoughts on being a programmer by aneisf on Tuesday August 14, 2012 @09:10PM (#4383920)
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.

Re:Thoughts on being a programmer by paul-woolcock on Wednesday August 15, 2012 @08:53AM (#4385690)
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.
Re:Thoughts on being a programmer by aneisf on Wednesday August 15, 2012 @07:00PM (#4388788)
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.
Re:Thoughts on being a programmer by mgurlitz on Wednesday August 15, 2012 @09:17AM (#4385796)
Wouldn't the Pythonic thing be to only fail after you've tried, instead of validating your parameters in advance?
Re:Thoughts on being a programmer by agentultra on Wednesday August 15, 2012 @10:00AM (#4385952)
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.
Re:Thoughts on being a programmer by DeepDuh on Wednesday August 15, 2012 @09:49AM (#4385911)
Is that really Pythonic? Isn't that just general best practice in programming?
Re:Thoughts on being a programmer by anthonyb on Tuesday August 14, 2012 @07:42PM (#4383648)
In fewer words: comment why, not what.
Re:Thoughts on being a programmer by einhverfr on Tuesday August 14, 2012 @11:32PM (#4384424)
I prefer:

Comment why, not how.

Re:Thoughts on being a programmer by einhverfr on Tuesday August 14, 2012 @11:01PM (#4384275)
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 ;-)