5 ms·

"Same way comments are extra weight that should only be in public or algorithm/need to know areas. " Best thing I learned about commenting is: Comment WHY you

• jimmaswell 9y ago
  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.
  • collyw 9y ago
    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.