47 ms·
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, rewri
by FuzzyDunlop 14y ago
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 14y agoWe 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 14y agoNot 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 14y agoThat 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 14y agoThat 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.
- mgurlitz 14y agoWouldn't the Pythonic thing be to only fail after you've tried, instead of validating your parameters in advance?
- agentultra 14y agoYes. 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 14y agoIs that really Pythonic? Isn't that just general best practice in programming?
- aneisf 14y agoI'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.
- anthonyb 14y agoIn fewer words: comment why, not what.
- einhverfr 14y agoI prefer: Comment why, not how.
- einhverfr 14y agoExactly. 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 ;-)