How to comment constant values?

[Erwin Mueller]

Hello, I'm new to Python (using it for two months) and I wonder how can I
comment the const. values with the doc-strings. I.e. if I have code:

>FRACTION_MIN = 1
>FRACTION_MAX = 10
>
>class Fraction(collections.MutableSequence):
> '''Model a fraction with denominators.
>
> It contains one ore more denomintors in a list for quick access.
> The class is thread save, it uses a lock for all operations.
> '''
>
> def __init__(self):
> # ...

The class and the methods can have doc-strings, but what about the const.
values, FRACTION_MIN and FRACTION_MAX?

Thank you, Erwin.

[Chris Rebert]

Only modules, classes, and functions/methods can have docstrings
associated with them.
For anything else, you have to use comments; or you can mention them
in the docstrings of related things.

Cheers,
Chris
--
http://blog.rebertia.com

[Bearophile]

Chris Rebert:

> Only modules, classes, and functions/methods can have docstrings
> associated with them.
> For anything else, you have to use comments; or you can mention them
> in the docstrings of related things.

What about adding docstrings to other Python things, especially to
variables?

Bye,
bearophile

[Diez B. Roggisch]

Chris Rebert schrieb:

While this is technically true, writing docstrings to constants (module
or classlevel) works when one uses tools such as epydoc to generate
documentation.

Diez

[Steven D'Aprano]

Python doesn't have variables, it has objects bound to names. Because
__doc__ is looked up on the class, not the instance, there's not much
point in adding a docstring to the instance (even for instances which
allow attributes to be added). And because names are internally stored as
strings, you can't add a docstring to the name. So what you ask for is
impossible.

But of course that could be changed, if there was consensus that what you
ask for would be useful. But consider the consequences:

# A thought-experiment
>>> margin = 3 # allow a little bit of whitespace
>>> margin.__doc__ = "Extra space in pixels."
>>> help(x)
=> displays "Extra space in pixels."

So far so good. But now consider two equally unacceptable situations:

(1) If the docstring sticks to the object, then you get the docstring
inappropriately showing up in places where it should:

>>> number_of_widgets = len( [a, b, c] )
>>> help(number_of_widgets)
=> displays "Extra space in pixels."

(2) If the docstring sticks to the name, then you get the docstring
hanging around when you recycle the name to mean something else:

>>> margin = 15/100.0 # our profit margin is 15%
>>> help(margin)
=> displays "Extra space in pixels."

Now, in a large program, one shouldn't recycle names like that, but in a
large program, you're unlikely to programmatically look up docstrings.
Docstrings, and the help() function, are particularly useful in an
interactive session, which is precisely the time that you're likely to
recycle names.

In other words, it's currently impossible to bind docstrings to
"variables" in Python, but even more fundamentally, the request is
semantically incompatible with the Python name/object binding model.

--
Steven

[Steven D'Aprano]

On Mon, 27 Jul 2009 00:47:08 +0200, Diez B. Roggisch wrote:

>> Only modules, classes, and functions/methods can have docstrings
>> associated with them.
>> For anything else, you have to use comments; or you can mention them in
>> the docstrings of related things.
>
> While this is technically true, writing docstrings to constants (module
> or classlevel) works when one uses tools such as epydoc to generate
> documentation.

I've never used epydoc, so I'm not sure what you mean. Presumably it uses
source code analysis to detect:

CONSTANT = 42
"""This is a constant."""

even though the string is ignored by the compiler.

Is that correct?

--
Steven

[Robert Kern]

epydoc 3 can actually parse the file to grab comments with a "#:" marker:

#: This is a constant.
CONSTANT = 42

--
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco

[Jean-Michel Pichavant]

Yes, and because it is perfectly ignored by the compiler there's no harm
using this feature. I would add that even if you're not using epydoc,
having a way top discriminate comments from documentation is
recommended, their purpose are definitely not the same.

JM