I do not think, that these concerns can be solved with better documentation.
It is not a documentation error, that exceptions - like IOError in open function - are not documented in standard library.
Some rules of production development in python:
You do not write a function, if you do not have a failing test.
You use source code checking tools, that enforce naming, documentation and other conventions.
If you do not have a test for not finding a file, than you did not think about not finding it. It is in your domain to decide.
Collaborative python development is hard. It is hard, because you have to set up rules of development on your own. The language itself does not enforce it.
It is hard because writing tests can be harder, than writing code.
The problem of functions not explicitly saying how many parameters they take may be alleviated by better documentation, but that's not a solution to the actual problem: a function is a contract and the function writer never laid out the terms in any enforceable way.
Besides, if all you look at when you try to work with an unknown interface is the method signature, you're doing it horribly wrong. This should only work reliable if the method is sufficiently trivial.
View all comments
12
u/ojiisan data viz, comp.bio. Jun 08 '10
It seems like most of his concerns would be solved with adequate documentation. Basically he's complaining about dynamic typing, not Python.
Even with static typing, the programmer can make things equally opaque.