How to comment constant values?
Jean-Michel Pichavant
jeanmichel at sequans.com
Mon Jul 27 10:17:13 EDT 2009
Steven D'Aprano wrote:
> 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?
>
>
>
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
More information about the Python-list
mailing list