4 ms·

I've had this discussion a couple of times, but have failed to identify any pristine examples of essential documentation 'in the wild' myself. I'd like to know

by rch 13y ago

I've had this discussion a couple of times, but have failed to identify any pristine examples of essential documentation 'in the wild' myself. I'd like to know of a couple - I'm sure they are out there. Edit: Not project documentation, strictly code comments.

MartinCron 13y ago
I tend to have the "comments are an apology" mindset, where I will write a comment to apologize if something is partially implemented, counter-intuitive, driven by a byzantine external requirement, or an ugly workaround to someone else's bug. Those can totally be essential, as they will save someone (your future self, maybe) from attempting to refactor them to something simpler/cleaner that won't actually work.
dbarlett 13y ago
Example from real-world code I've written: if tag in tag_list: data[u"Tag"] = tag try: if i["DupilcateAssets"] is not None: # not a typo - misspelled in Dell SOAP response data[u"Error"] = "Duplicate assets returned" Would you want to debug that without the comment?
- rch 13y ago
  Agreed - I'd really appreciate coming across that one. It probably isn't the definitive example I'm looking for though.
- mpweiher 13y ago
  Gladly: sillyMisspelledDellSOAPIdentifier = "DupilcateAssets" if i[sillyMisspelledDellSOAPIdentifier] is not None:
  - dded 13y ago
    But this is largely a comment disguised as a variable name, and is no more or less likely to stay up-to-date as a comment. If the Dell Identifier were to ever be changed to "DuplicateAssets", you're just as likely to have sillyMisspelledDellSOAPIdentifier = "DuplicateAssets" as the original might have if i["DuplicateAssets"] is not None: # Not a typo... And your method replaces one line of code with two. Comments have problems, but they solve problems too. They're not evil.
- jheriko 13y ago
  some comments are very useful, this is a great example
- aerique 13y ago
  Why not just: if i["DupilcateAssets"] is there some Python subtlety I am missing?
  - cma 13y ago
    In python some things evaluate as false in an if or boolean conversion (0, an empty list/tuple/set/dict/user_defined, an empty string "", and more). None evaluates as false as well, but is still distinguishable from the rest. In ruby you likewise sometimes need to use object.nil? because nil and False are both "false-ish".
- raverbashing 13y ago
  This is a great example of a comment that should (or even must) be there. If something doesn't work the way it should and it's beyond your control, comment it.

by rch 13y ago

MartinCron 13y ago

I tend to have the "comments are an apology" mindset, where I will write a comment to apologize if something is partially implemented, counter-intuitive, driven by a byzantine external requirement, or an ugly workaround to someone else's bug. Those can totally be essential, as they will save someone (your future self, maybe) from attempting to refactor them to something simpler/cleaner that won't actually work.

dbarlett 13y ago

Example from real-world code I've written: if tag in tag_list: data[u"Tag"] = tag try: if i["DupilcateAssets"] is not None: # not a typo - misspelled in Dell SOAP response data[u"Error"] = "Duplicate assets returned" Would you want to debug that without the comment?

rch 13y ago
Agreed - I'd really appreciate coming across that one. It probably isn't the definitive example I'm looking for though.
mpweiher 13y ago
Gladly: sillyMisspelledDellSOAPIdentifier = "DupilcateAssets" if i[sillyMisspelledDellSOAPIdentifier] is not None:
- dded 13y ago
  But this is largely a comment disguised as a variable name, and is no more or less likely to stay up-to-date as a comment. If the Dell Identifier were to ever be changed to "DuplicateAssets", you're just as likely to have sillyMisspelledDellSOAPIdentifier = "DuplicateAssets" as the original might have if i["DuplicateAssets"] is not None: # Not a typo... And your method replaces one line of code with two. Comments have problems, but they solve problems too. They're not evil.
jheriko 13y ago
some comments are very useful, this is a great example
aerique 13y ago
Why not just: if i["DupilcateAssets"] is there some Python subtlety I am missing?
- cma 13y ago
  In python some things evaluate as false in an if or boolean conversion (0, an empty list/tuple/set/dict/user_defined, an empty string "", and more). None evaluates as false as well, but is still distinguishable from the rest. In ruby you likewise sometimes need to use object.nil? because nil and False are both "false-ish".
raverbashing 13y ago
This is a great example of a comment that should (or even must) be there. If something doesn't work the way it should and it's beyond your control, comment it.