Re:Avoid Else, Return Early (2013)
by jimmaswell on Monday March 26, 2018 @04:38PM
(#16682352)
If you feel the need to specify in a comment that the code does some potentially unexpected thing or that the way it does what it does has certain consequences, that's fine. And obviously the comment/doc of a function/class/whatever should say what it does if it's not 100% obvious and unambiguous from the name. I don't think this kind of rule is really helpful. Just comment if you feel a comment is needed, and if other people who interact with your code think you have too many or too few comments then you can adjust from there.
People do need to be taught this. I inherited a script from a co-worker who had left. My team leader had gone over it and commented it for me.
# open file
with open(my_file, "rb") as binary_file:
binary_file.seek(8)
No mention of what was at byte 8, or what the hell it was doing, but he commented the only obvious part of the code.
" Best thing I learned about commenting is: Comment WHY you are doing it... not WHAT. Code is the WHAT... Comment is the WHY