[Python-Dev] PEP 257 and __init__

[Fred Drake]

On Tue, Dec 29, 2015 at 1:27 PM, Facundo Batista
<facundobatista at gmail.com> wrote:
> I was reading PEP 257 and it says that all public methods from a class
> (including __init__) should have a docstring.
>
> Why __init__?
>
> It's behaviour is well defined (inits the instance), and the
> initialization parameters should be described in the class' docstring
> itself, right?

__init__ is not always the only constructor for a class; each
constructor's arguments should be documented as part of the
constructor.  The class docstring should provide summary information
for the class as a whole.

I can also imagine cases where the __init__ isn't considered public,
though I suspect that's exceedingly rare in practice.  (Can't think of
a case I've actually run across like that.)

> Should we remove "__init__" (the class method, *not* the package file)
> as to require docstrings in the PEP?

I don't think so.  The advice seems sound to me.


  -Fred

-- 
Fred L. Drake, Jr.    <fred at fdrake.net>
"A storm broke loose in my mind."  --Albert Einstein