pre-PEP for optional 'pass'

[brueckd at tbye.com]

On Wed, 17 Apr 2002, Duncan Booth wrote:

> <brueckd at tbye.com> wrote in
> news:mailman.1018972676.30534.python-list at python.org:
>
> >> You should always head each method and class with a docstring.
> >
> > No! You should head each method and class with a docstring *only if
> > the docstrings would add value*. Otherwise you're doing more work now
> > AND later (during refactoring) without producing any real benefit,
> > cluttering the code in the process.
>
> I kind of agree with you while standing by my original statement.

(IOW: "I must get in the last word" :-) )

> In the context of the original message, where the poster was proposing
> writing a function that only contained 'pass', they could always use a
> good docstring instead.

Perhaps, with heavy emphasis on 'good'. This may seem like a nitpick, but
it does play an important part in writing clean, readable code. The
absolute best docstring is none at all because something is so darn
obvious that it doesn't need one.  Many (but not all) get/set methods fall
into this category.

> Even if the docstring simply says that the function is
> unimplemented this provides useful information to anyone who does not have
> the original source in front of them.

Quite an esoteric case, really: someone has the .pyc of a half-baked .py
with no explanation of what is unfinished. Most people won't read the
docstrings anyway, so in the case it'd be better to raise a not
implemented exception.

Docstrings and comments put in your code just to satisfy some sort of
documentation requirement ("all classes and all methods should have a
docstring") are distracting and detrimental to code readability and make
refactoring more of a chore. I believe _Code Complete_ has a chapter or
two worth reading on this subject, and the author does a much better job
explaining it that I have.

Moving on....

-Dave