Principles of documentation

[Josiah Carlson]

> We're different--always interesting.  As a heavy consumer and
> producer of documentation, "having the type .. in the function
> definition is convenient" intrigues me.  Clouding my thoughts
> a bit is C's wimpy type system ('love the language, 'recognize
> its limits).  Your proposition sounds to me much like what we
> used to believe about compile-time syntax checking, versus
> more robust and application-specific unit tests.

Goodness, please don't lump me with the compile-time syntax checking 
zealots *wink*.  I'm talking about convenience in documentation of C/C++ 
functions; it tells you what you /should/ be passing in.  No more, no 
less.  I find reading such type signatures to be quicker than linguistic 
descriptions of the passed arguments.

One really nifty thing about decorators (PEP 318) is that people will 
have the option of strong and dynamically typed polymorphism, but the 
drawback is that we may get some C++ or Java programmers who use it for 
everything, even when it is not necessary or detrimental.


> My preliminary reaction, therefore:  yes, indeed, type declar-
> ations are important, Python documenters should be particularly
> careful always to specify them explicitly, and, if anything,
> Python has the chance to improve on the standards C and C++ set,
> as its typing is stronger.

Agreed.

  - Josiah