Comments about what something is doing are both the least useful and most likely to go out of date. Comments about why something is happening are in my experie

Comments about what something is doing are both the least useful and most likely to go out of date. Comments about why something is happening are in my experience much more useful. An example: # Using an if / elif rather than a select here Rather than: # Use a large if / elif statement here due to a regression in TCL 8.4 which made select statements significantly slower. See GitHub.com/tcl-bugs.