docstrings style question

[Neil Cerutti]

On Jan 10, 2008 12:47 AM, Steve Brown <steve at mhomer.au> wrote:
> I've got a series of modules which look like this:
>
> #************
> #
> # Temperature Sense Test
> #
> #************
> class Test3(ar_test.AR_TEST):
>     """Temperature Sense Test"""
>
>
> I don't like the duplicated information: But the comment is attractive, and
> the docstring self.__doc__ is already in use in the test log. I've read that
> all modules and classes should have docstrings, but I don't really have
> anything else to say, and each module contains only one class. I don't think
> that
>
> """Temperature Sense Test"""
> class Test3(ar_test.AR_TEST):
>     """Temperature Sense Test"""
>
> would be a real improvement.
>
> What do you think?

I recommend a careful reading of PEP 257.

You shouldn't waste your time creating (at best) decorative comments, like:
#************
#
# Temperature Sense Test
#
#************
class Test3(ar_test.AR_TEST):
     """Temperature Sense Test""

Remember that comments have to maintained along with the rest of the
code, so unnecessary ones just create more work for you. Any time you
can replace a comment with self-explanatory code, you should.

Here's a vast improvement:

class TemperatureSenseTester(ar_test.AR_TEST):

-- 
Neil Cerutti <mr.cerutti+python at gmail.com>