[lmm]

Nope. You need to comment every nonobvious decision, but if you write code the right way then the nonobvious decisions disappear. A well-written method doesn't need explanation, because it obviously couldn't have been written any other way.

[peteretep]

> A well-written method doesn't need explanation, because it obviously couldn't have been written any other way

I don't think I have anything nice I can say here, other than this smacks of the hopeless naivety

[vetler]

One problem with this, is that it's probably subjective what nonobvious code actually is. Of course, it's subjective how much commenting is enough, as well. In my experience, projects where it has been decided that comments are not required, have ended up with uncommented and nonobvious code - the worst of both worlds.

This could perhaps been prevented given proper code review processes, that were not in place. However, in a project with varied skill level, I would personally prefer advocating both commenting and obvious code, since the end result will probably be something inbetween.

[hnwh]

I'd really like this to be reality.. but in my world, there are too many programmers who don't write code "the right way". like > %80. For the great programmers sure ok, its obvious, but for the rest of them.. no.. you're not the coding genius you think you are.. please comment your code. Don't be tricky, clever, smart.. or self-documenting. Comment. period.

[yummyfajitas]

If a programmer is incapable of doing this:

    maybeGetFileHandle :: FilePath -> IOLikeMonad (Maybe Handle)

Why do you think they are capable of doing this?

    foo :: FilePath -> IOLikeMonad (Maybe Handle)
    -- If the file is available and can be read
    -- return Some handle. Otherwise, return None.

[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.

[olavk]

    // NOTE: Workaround for a bug in the framework
    // foo will crash if you foo before bar.
    // Here we bar with a null value, which prevents the crash
    bar(NULL);