docstrings style question

[Martin Marcher]

Russ P. wrote:

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

It's still duplicated information.

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

exactly my opinion

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

I tend to mention the main use cases for test classes (especially) and also
a "human readable" description of what can happen (forgive me the missing
line breaks). Something like this:

class Test3(ar_test.AR_TEST):
    """Temperature Sense Test.
    This class assures that the connection to the hardware sensor can be
established. It also checks a reference sensor that always reports a
certain value so that one can be sure correct data values are reported.
    """

hth
martin

-- 
http://noneisyours.marcher.name
http://feeds.feedburner.com/NoneIsYours

You are not free to read this message,
by doing so, you have violated my licence
and are required to urinate publicly. Thank you.