3 ms·
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,
by 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 agoPeople 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.