How to comment constant values?
jeanmichel at sequans.com
Mon Jul 27 16:17:13 CEST 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
> 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.
More information about the Python-list