[jberryman]

> But the problem with comments is that they'll inevitably get out of sync with the code.

Eek, then by all means take comments seriously and change them when your code changes. I think it's particularly important to comment functions and methods (especially effectful/stateful ones) with what precisely they're expected to do, what invariants hold, etc. (insofar as the type system and function name don't make these clear). Otherwise another programmer has no way (aside from looking at and completely understanding every call site) of knowing what bits of the functionality are incidental vs intended behavior, and are likely to make small modifications for their own purposes which break other things.

Programmers seem very eager to lack of comments and I'm super unsympathetic; this is the one thing that just kills me. Comments hold together a codebase, make it much easier to learn and read, and are a way for programmers to impart all sorts of bits of knowledge about the domain that is valuable "we would do X here but foo() from library Y works in such and such a way so, blah blah blah". And if you don't like to read comments like that I'm sure your editor will fold them for you.