[sparkie]

A nice example which expresses the bulk of the issue: Comments are largely there to compensate for the lack of information held in the type system. Adding comments which just reiterate what is said in the function signature is redundant and not worth the time.

Of course, this doesn't apply to all comments - but specifically those insane policies where you're required to write a description of every method, argument and return type.

The more powerful the type system, the less necessary comments become. If you take a dependent type system for example, or some code contracts with explicit preconditions, you no longer need to specify the valid range of values for a given function in some silly comments which will fall on deaf ears in the majority of cases anyway. The programmer will be stopped and forced to read it, rather than waiting until runtime to discover the correct behavior, if at all.

[yummyfajitas]

I wasn't actually trying to make a statement about type systems. To translate my example to python:

    def getFileHandleOrNone(filename, config):
        ...

    def foo(filename, config):
        """get file handle or none, 
           based on context and filesystem"""

You are correct that the type system also provides documentation, but so does giving your methods a name indicating what you want them to do.