473,231 Members | 1,389 Online
Bytes | Software Development & Data Engineering Community
Post Job

Home Posts Topics Members FAQ

Join Bytes to post your question to a community of 473,231 software developers and data experts.

docstrings style question

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.
Jan 10 '08 #1
6 1151
On Jan 9, 9:47 pm, "Steve Brown" <st...@mhomer.auwrote:
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.
Jan 10 '08 #2
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>

Jan 10 '08 #3
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

Jan 10 '08 #4
Russ P. wrote:
On Jan 9, 9:47 pm, "Steve Brown" <st...@mhomer.auwrote:
>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.

Jan 10 '08 #5
On Jan 10, 2008 12:47 AM, Steve Brown <st***@mhomer.auwrote:
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***************@gmail.com>
Jan 10 '08 #6

"Neil Cerutti" <mr********@gmail.comwrote in message
news:ma************************************@python .org...
On Jan 10, 2008 12:47 AM, Steve Brown <st***@mhomer.auwrote:
>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***************@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
Jan 11 '08 #7

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

2
by: Sridhar R | last post by:
When writing a python library, we can use docstrings for methods and functions that are part of API. But what about comments for non-API objects or python application code? For applications,...
0
by: Craig Ringer | last post by:
Hi folks I'm currently working on a fairly well internationalised app that embeds a Python intepreter. I'd like to make the docstrings translatable, but am running into the issue that the...
2
by: Steven Bethard | last post by:
I have two classes that implement the same interface, e.g. something like: class C(object): def foo(self): """Foo things""" ... def bar(self): """Bar things""" ... def baz(self):
6
by: Kamilche | last post by:
I have a large project that is getting complex, and I would like to print the docstrings without importing the modules. The only Python utility I could find references is apparently defunct and...
0
by: Edward Loper | last post by:
Epydoc 3 supports extracting information about Python modules by parsing. As a result, it can extract "docstrings" for variables. There are several possible ways these docstrings could be...
12
by: jelle | last post by:
That's basically the idea... Often i find myself annotating what variables actually stand for, so to refer back to the code in half a year or so. # check if ID's or coords self.pointIDs = ptIDs...
1
bartonc
by: bartonc | last post by:
You will be rewarded sooner than you think when you use docstrings to document your classes and functions. Whether you ever intend to publish your work or not, docstrings will help you in several...
0
by: tjhnson | last post by:
The topic of docstrings for variables has come up many times before. In fact, a PEP was proposed and rejected on this very topic. http://www.python.org/dev/peps/pep-0224/ When creating...
1
by: Infinity77 | last post by:
Hi All, I apologize in advance if my question sounds dumb. I googled back and forth but my google-fu today is not working very well... I have seen the new style Python html documentation, which...
0
by: VivesProcSPL | last post by:
Obviously, one of the original purposes of SQL is to make data query processing easy. The language uses many English-like terms and syntax in an effort to make it easy to learn, particularly for...
3
isladogs
by: isladogs | last post by:
The next Access Europe meeting will be on Wednesday 3 Jan 2024 starting at 18:00 UK time (6PM UTC) and finishing at about 19:15 (7.15PM). For other local times, please check World Time Buddy In...
0
by: abbasky | last post by:
### Vandf component communication method one: data sharing ​ Vandf components can achieve data exchange through data sharing, state sharing, events, and other methods. Vandf's data exchange method...
0
Git
by: egorbl4 | last post by:
Скачал я git, хотел начать настройку, а там вылезло вот это Что это? Что мне с этим делать? ...
1
by: davi5007 | last post by:
Hi, Basically, I am trying to automate a field named TraceabilityNo into a web page from an access form. I've got the serial held in the variable strSearchString. How can I get this into the...
0
by: MeoLessi9 | last post by:
I have VirtualBox installed on Windows 11 and now I would like to install Kali on a virtual machine. However, on the official website, I see two options: "Installer images" and "Virtual machines"....
0
by: DolphinDB | last post by:
The formulas of 101 quantitative trading alphas used by WorldQuant were presented in the paper 101 Formulaic Alphas. However, some formulas are complex, leading to challenges in calculation. Take...
0
by: Aftab Ahmad | last post by:
Hello Experts! I have written a code in MS Access for a cmd called "WhatsApp Message" to open WhatsApp using that very code but the problem is that it gives a popup message everytime I clicked on...
0
by: Aftab Ahmad | last post by:
So, I have written a code for a cmd called "Send WhatsApp Message" to open and send WhatsApp messaage. The code is given below. Dim IE As Object Set IE =...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.