[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.python

docstrings style question

Steve Brown

1/10/2008 5:48:00 AM

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

Russ P.

1/10/2008 7:40:00 AM

0

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

Fredrik Lundh

1/10/2008 7:52:00 AM

0

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

since you already seem to cater to your audience (clearly marked
comments for people browsing the code, brief docstrings for the test
log), I don't really see why you should change anything.

> I've read that all modules and classes should have docstrings

if nobody's going to read them, there's no reason to add them. don't
treat generic style advice as dogma.

</F>

Russ P.

1/10/2008 8:04:00 AM

0

On Jan 9, 11:51 pm, Fredrik Lundh <fred...@pythonware.com> wrote:
> Steve Brown 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?
>
> since you already seem to cater to your audience (clearly marked
> comments for people browsing the code, brief docstrings for the test
> log), I don't really see why you should change anything.
>
> > I've read that all modules and classes should have docstrings
>
> if nobody's going to read them, there's no reason to add them. don't
> treat generic style advice as dogma.
>
> </F>

Well, trivial modules certainly don't need much documentation, but he
didn't say they were trivial. I assumed there was more to them then he
showed.

Jeroen Ruigrok van der Werven

1/10/2008 8:11:00 AM

0

-On [20080110 06:51], Steve Brown (steve@mhomer.au) wrote:
>I don't like the duplicated information: But the comment is attractive,

I find it unattractive to be honest.

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

The ultimate test is running `pydoc your.module` or running epydoc on your
source and see how well the resulting documentation is built up.

--
Jeroen Ruigrok van der Werven <asmodai(-at-)in-nomine.org> / asmodai
ã?¤ã?§ã?«ã?¼ã?³ ã?©ã?¦ã??ã?­ã??ã?¯ ã?´ã?¡ã?³ ã??ã?« ã?¦ã?§ã?«ã?´ã?§ã?³
http://www.in-n... | http://www.ra...
The quieter you become, the more you are able to hear...

Ryan Ginstrom

1/10/2008 9:45:00 AM

0

> On Behalf Of Steve Brown
> What do you think?

I think that comments are for maintainers, and docstrings are for users.

Some of the things I use comments for:
* Visually separate classes (using a syntax-highlighting editor)
* Explain algorithm choices
* Explain bug fixes so I don't later "fix" code back to the buggy version

Some of the things I use docstrings for:
* Describe interface (inputs/outputs)
* Sample usage

I personally don't use doctests, but that's one more use of docstrings.

Regards,
Ryan Ginstrom

Martin Marcher

1/10/2008 10:11:00 AM

0

Russ P. wrote:

> On Jan 9, 9:47 pm, "Steve Brown" <st...@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.ma...
http://feeds.feedburner.com/N...

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

Steve Brown

1/10/2008 10:31:00 AM

0


"Russ P." <Russ.Paielli@gmail.com> wrote in message
news:d2a08eac-3ae7-4710-9b49-cdbe365a25ef@d21g2000prf.googlegroups.com...
> On Jan 9, 11:51 pm, Fredrik Lundh <fred...@pythonware.com> wrote:
>> Steve Brown 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?
>>
>> since you already seem to cater to your audience (clearly marked
>> comments for people browsing the code, brief docstrings for the test
>> log), I don't really see why you should change anything.
>>
>> > I've read that all modules and classes should have docstrings
>>
>> if nobody's going to read them, there's no reason to add them. don't
>> treat generic style advice as dogma.
>>
>> </F>
>
> Well, trivial modules certainly don't need much documentation, but he
> didn't say they were trivial. I assumed there was more to them then he
> showed.

All of the complexity is in the test framework. I've been working on paring
back the tests to make them simple to understand, create and modify, which
is how I've come to this: I'm still trying to remove lines. The test itself
is a now a linear script of 20-40 lines, and I'm still working on them.

However, it is relatively important to make the documentation right for
these simple scripts.

The docstring/comment does need to show some embedded dependancies, I just
chose one without any.

I realise from reading Jeroen Ruigrok van der Werven's comment that I should
probably also
care what epydoc makes of my doc strings, -- that's an additional
constraint.


Neil Cerutti

1/10/2008 2:04:00 PM

0

On Jan 10, 2008 12:47 AM, Steve Brown <steve@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@gmail.com>

Steve Brown

1/11/2008 2:02:00 AM

0


"Neil Cerutti" <mr.cerutti@gmail.com> wrote in message
news:mailman.408.1199973821.896.python-list@python.org...
> On Jan 10, 2008 12:47 AM, Steve Brown <steve@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@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


Steve Brown

1/11/2008 2:09:00 AM

0

What I'm trying to do with the tests is pare them back so that
the code explicitly and concisely documents the tests.

It is important that the comments and doc strings NOT contain
information about how Temperature Sense works because that
is outside the scope of the test.

More generally, comments like this

i++ #increments i

indicate that the author thinks that the most complex thing
present is the syntax, a comment like this:

i++ #next voltage

indicates that the author thinks the most complex thing present
is the variable mapping.

For the readers and maintainers of these tests, the most complex
thing present is the syntax, not the test logic, so if I need to add
more documentation, it will look like this:

# Temperature Sense Test
# Lines starting with # are comments
# Variables are case sensitive
# Tab characters will break this file

-- and go from there.

Steve


"Martin Marcher" <martin@marcher.name> wrote in message
news:mailman.397.1199959984.896.python-list@python.org...
> Russ P. wrote:
>