[Grok-dev] single or double backticks?

[Uli Fouquet]

Hi Brandon,

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.
(See http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html)

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:

     class Keeper(Storer):

        """
        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:
    use_single_quotes()
  else:
    use_double_quotes()

Could that be a Right Way?

Best regards,

-- 
Uli

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Dies ist ein digital signierter Nachrichtenteil
Url : http://mail.zope.org/pipermail/grok-dev/attachments/20081213/115e7d81/attachment.bin