I agree that naming things well is a great way to document them. However I think that in most of the codebases I've worked on it is quite common for a function/

I agree that naming things well is a great way to document them. However I think that in most of the codebases I've worked on it is quite common for a function/method to do many things some of which are incidental and some necessary, and it would be difficult to include the full set of these in the method's name. (comments also help to make it obvious when a function is, perhaps, too complex and arbitrary). In addition to good naming, strong static types and functional purity help a great deal (but I won't try to evangelize haskell here :)) > ...hidden (because if someone is reading code that calls myVeryWellDocumentedFunction, they won't see the documentation, especially if the function is just incompletely named) what is your proposed alternative? Ideally a function would do the only possible sensible thing imaginable, but that is frequently not attainable. > ...inaccurate (because the only accurate thing is the code) Well when the code doesn't match the spec in the comments, we've found a bug in the code, or a bug in the spec. Either way we can find someone to blame. This is vastly better than finding a bug and not knowing whether the function or the caller should be fixed.