[Grok-dev] single or double backticks?
uli at gnufix.de
Fri Dec 12 21:10:33 EST 2008
Brandon Craig Rhodes wrote:
> The Zope code base seems pretty evenly split between using
> `singleBackticks` when quoting literals and using ``doubleOnes``. Which
> is our preferred style, so that I can do the Right Thing as I'm writing
> these docstrings for Grok?
Glad you asked that, because I was also confused about that.
While hoping this won't become a religious topic, I would prefer
`singleBackticks` for referencing terms (modules, function names, vars)
and ``doubleOnes`` for pieces of simple literal text like
``'simple_string'``, ``23``, etc. that do not reference something else.
Docutils say `single-quoted` text is "interpreted, meant to be related,
indexed, linked, summarized, or otherwise processed" while
``double-quoted`` text is pure inline literal text.
This means, single-quoted terms might be interpreted by some framework
(like 'sphinx') and thus it could be useful to use single quotes where
you refer to some other code entitiy.
PEP 287, which might be our more authoritative guide here, does not
mention double quotes but uses single quotes in most examples and
explains (See http://www.python.org/dev/peps/pep-0287/):
Text enclosed in single backquotes is recognized as "interpreted
text", whose interpretation is application-dependent. In the context
of a Python docstring, the default interpretation of interpreted
text is as Python identifiers. The text will be marked up with a
hyperlink connected to the documentation for the identifier given.
Lookup rules are the same as in Python itself: LGB namespace lookups
(local, global, builtin). The "role" of the interpreted text
(identifying a class, module, function, etc.) is determined
implicitly from the namespace lookup. For example:
Keep data fresher longer.
Extend `Storer`. Class attribute `instances` keeps track
of the number of `Keeper` objects instantiated.
instances = 0
"""How many `Keeper` objects are there?"""
So, to sum it up::
if term is ReferenceToSomeOtherCodePiece:
Could that be a Right Way?
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 189 bytes
Desc: Dies ist ein digital signierter Nachrichtenteil
Url : http://mail.zope.org/pipermail/grok-dev/attachments/20081213/115e7d81/attachment.bin
More information about the Grok-dev