pre-PEP for optional 'pass'

[Duncan Booth]

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


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

Yes, but since I have no idea what any of these methods actually does, I 
couldn't be bothered to guess at a useful docstring. Actually that isn't 
true: I know exactly what these methods do (zilch), but I have no idea why 
anyone might have written them.

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

Or you should edit it so it contains some useful content.
Here is another go at the class above

class MyClass:
   '''A completely useless class with no obvious purpose in life'''
   def __init__(self, x, ,y, z):
      '''Parameters x, y, and z are all dropped in the bit bucket.
         Perhaps we are passed them for compatibility with something
         else in which case we could say what...'''
   def getTwiddle(self):
    	 '''Despite the implications of its name, this method actually
         returns None. It also has no side effects and should therefore
         be refactored out.'''
   def setTwiddle(self, twiddle):
      '''Whatever a twiddle may be, this method actually drops the
         argument and does nothing useful. Returns None. Another
         refactoring candidate.'''

I would say that all of these comments could be automatically generated, 
but if I look at the output of (say) pydoc, they add useful information as 
I might otherwise be misled into thinking that the class and methods did 
something.

-- 
Duncan Booth                                             duncan at rcp.co.uk
int month(char *p){return(124864/((p[0]+p[1]-p[2]&0x1f)+1)%12)["\5\x8\3"
"\6\7\xb\1\x9\xa\2\0\4"];} // Who said my code was obscure?