docstrings style question

[Russ P.]

On Jan 9, 9:47 pm, "Steve Brown" <st... 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?
>
> Steve.

I tend to be a bit skimpy with one-line comments for classes and
methods, but I think a more complete (""" style) comment is often
appropriate for the top of the file.

I'm sure you can think of more to say than "Temperature Sense Test."

What temperature? What kind of temperature sensor? What kind of test
is it, and why are you doing it? That may all be obvious in context,
but you've provided no context in your post. Also, if the module is of
any significant size, you might want to provide a clue about who wrote
it. Then, if someone has a question about it later, they will know who
to ask.