I don't think I have anything nice I can say here, other than this smacks of the hopeless naivety
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.
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.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.
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. // 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);