pre-PEP for optional 'pass'

[brueckd at tbye.com]

On Tue, 16 Apr 2002, Duncan Booth wrote:

> 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.

> class MyClass:
>    '''A simple class'''
>    def __init__(self, x, ,y, z): '''MyClass constructor'''
>    def getTwiddle(self): '''Get a twiddle'''
>    def setTwiddle(self, twiddle): '''Set a twiddle'''

The above code snipped contains exactly 4 examples of docstrings that
should not exist - all of them either contain no useful information or no
information that isn't already painfully obvious.

A good rule of thumb is that if the docstring (or comment) could have been
auto-generated by your editor, you shouldn't include it.

-Dave