The best place for documenting code, ranked from best to worst: * the code itself - I.e. function names, class names, parameter names * test and assertion nam

The best place for documenting code, ranked from best to worst: * the code itself - I.e. function names, class names, parameter names * test and assertion names * comments in code * comments in tests * version control repository commits * some external documentation repo like Confluence or MediaWiki Comments are good when they describe why, not how or what. For example, good comments might be "Had to do it this way to support v2 of the API". I hate going to documentation for an API and seeing "setFoo() - sets the foo value".