Caps in doc strings (was: Re: Default indentation of 4 columns)

[François Pinard]

Paul Foley <mycroft at actrix.gen.nz> écrit:

[about using capitals or not in documentation strings]

> Interestingly, I use both conventions, but for different reasons (I
> didn't even know that the use of capitals _was_ a GNU convention; did know
> Knuth uses |vertical bars| for literals, but hadn't even considered that).

  [I wanted to include the Python list in this reply, and for doing so, took
  the liberty of quoting most of your message, which I found interesting
  and instructive, to provide enough context.]

In Texinfo, @var{xyz} is for documenting variables, and is rendered
with slanted fonts on a laser printer.  When converting to Info (that is,
ASCII), there is no slanted fonts, and capitals are used instead.  In fact,
exactly how various @style{...} are represented in ASCII is well documented.

The informal convention for doc strings is letting ourselves think Texinfo
(@code{...} for code elements, @samp{...} for string fragments, @var{...}
for variables or non-terminal symbols, @emph{...} for emphasis, etc.) and
just doing the Info rendering "by hand", following the standards set by
the Texinfo to Info conversion.

> I use capitals because that's the common case in Common Lisp; I use
> vertical bars for lowercase symbols for the same reason (Common Lisp uses
> vertical bars to read in a case-preserving manner).  Hence, I use vertical
> bars for Python variables and functions, because they're case-dependent and
> case-preserving, and capitals in languages that are either case-insensitive
> (e.g., Pascal) or that standardize on upper-case (e.g., Lisp).

I thought that, in Python, usual local variables, and formal arguments among
them, are to be conventionally set in lower case anyway, so the mixed case
difficulty does not apply in actual practice, even the language itself would
allow more variance.  No doubt that a coding style is a set of restrictions
over what a language permits, that we choose to follow for various reasons.

There is a lot of commonality (or at least, very little clash) between
Guido's recommendations and GNU standards about the naming convention for
identifiers, and it was part of my pleasure, reading the details of Python
coding style, to see that I had so little to change in my long lasting
habits.  (The main change was to learn how to use a bit less whitespace
at some specific places, like between a function and its argument list,
or around the `=' introducing keyword arguments -- and surprisingly,
it was very easy to get some speed on this).  I consider that Guido's
recommendations and GNU standards enlighten each other to a good extent.

Besides Emacs LISP, I have little recent exposure to various dialects
of LISP.  What I've seen from others' Scheme code (but that is not
much) seems to favour lower-case as well, and capitals for systemic
constants, nothing unusual for me.  Scheme ignores case in identifiers,
but this never precluded me to write exactly as if case was significant.
DSSSL, if I remember well, is a case-sensitive implementation of Scheme.
(So is Guile, the last I heard, but since Guile was not meant to be very
respectful of standards when initially designed, I return the favour by
not being very respectful of Guile; what Guile does do not matter much. :-)

> I think the "use caps" standard is a pretty bad idea in a case-sensitive
> case-preserving language like Python, since it doesn't let you distinguish
> between names that the same in all but case (common to make the distinction
> between class names and variable names, in Python).

Python and C (and Emacs LISP, for that matter) are quite similar in what they
permit for capitalisation, and what people actually use while writing these.
I quite understand what you mean by "use caps" standard being a pretty
bad idea, and I remember feeling uncomfortable when I started to use it,
thinking about those constants we always write in all capitals, before even
speaking of them in doc strings, and all the confusion that might result.

But I followed the capitalisation convention in doc strings for more than
a dozen years, being often quite active at programming, and I can ensure
you from experience that my fears were not justified.  That convention is
quite workable, it does not raise any real problem on the wide average.
I'm rather convinced, by now, that it is a legible way to write doc strings.
If we simultaneously follow the rest of naming conventions, that is! :-)

-- 
François Pinard   http://www.iro.umontreal.ca/~pinard