pre-PEP for optional 'pass'

[Andy Gimblett]

On Wed, Apr 17, 2002 at 08:33:44AM +0000, Duncan Booth wrote:

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

We're veering slightly from the original reason for this point, which
was how to write stub functions/methods which will be implemented
later.  The above certainly doesn't indicate any intent to actually
implement the methods (in fact, on the contrary, it suggests they
could be removed). 

How about this?

class MyClass:
    """Class encapsulating a Twiddle.  Unfinished.  Document me.  XXX"""
    def __init__(self, x, ,y, z):
        """Not yet implemented. XXX"""     
    def getTwiddle(self):
        """Not yet implemented. XXX"""     
    def setTwiddle(self, twiddle):
        """Not yet implemented. XXX"""     

where you can grep for XXX to find unfinished business - very handy.

-Andy

-- 
Andy Gimblett - Programmer - Frontier Internet Services Limited
Tel: 029 20 820 044 Fax: 029 20 820 035 http://www.frontier.net.uk/
Statements made are at all times subject to Frontier's Terms and
Conditions of Business, which are available upon request.