PEP 257: Docstring Conventions

Roman Suzi rnd at
Wed Jun 13 02:17:24 EDT 2001


I have some questions about docstrings:

1. Are the existing docstrings in Python standard modules
example of good docstrings according to this PEP?

2. Each time I wonder about this:

    - The docstring is a phrase ending in a period.  It prescribes the
      function's effect as a command ("Do this", "Return that"), not
      as a description: e.g. don't write "Returns the pathname ..."

Does it mean that docstring must describe interface, not 

But then again:

    The docstring for a function or method should 
1. summarize its behavior
2. document 
2.1. its arguments, 
2.2. return value(s), 
2.3. side effects
2.4. exceptions raised
2.5. restrictions on when it can be called (all if applicable).  
... Optional arguments should be indicated.  
... It should be documented whether keyword arguments are part of the

That is, docstring has nothing to do with internals of the


Sincerely yours, Roman A.Suzi
 - Petrozavodsk - Karelia - Russia - mailto:rnd at -

More information about the Python-list mailing list