docstrings style question

[Steve Brown]

"Neil Cerutti" <mr.cerutti at gmail.com> wrote in message 
news:mailman.408.1199973821.896.python-list at python.org...
> 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>

Yes, I'm working in that direction. At present there is still code that
parses the test sequence to get the class name, but I'm rebuilding that.

However, there will still be sufficient information for some of the tests
to justify one doc string or comment as well as the class name.

Is it possible to get from an object to a class module doc string?

Something like self.class.module.__doc__ ?

I'm not able to do an assignment inside the test class, because I have
to keep that clean, but I can do assignments inside the parent test class.


Steve