pre-PEP for optional 'pass'

[Steve Holden]

<brueckd at tbye.com> wrote in message
news:mailman.1018972676.30534.python-list at python.org...
> 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.
>
Unless, of course, you are a Microsoft employee documenting your latest
creation, in which case it is mandatory to include a section for every menu
option such as:

Edit | Frob | Unfrobnicate

The Edit | Frob | Unfrobnicate command unfrobnicates a frob that has
previously been frobnicated.

About the only thing you tend *not* to find in Microsoft documentation is a
sensible discussion of frobs and what they might do for you.

WHile I'm at it, I REALLY HATE those messages that tell me to contact my
system adminstrator when a problem has arisen. Makes me feel like shouting
"But I *am* the bloody system administrator" at the dialog box or error
message.

i-feel-better-now-ly y'rs  - steve
\