Docstring Convention: Python vs Emacs Lisp

,

here's a interesting stylistic clash between languages. Here's a excerpt from Python guide on docstring convention.

Do not use the Emacs convention of mentioning the arguments of functions or methods in upper case in running text. Python is case sensitive and the argument names can be used for keyword arguments, so the docstring should document the correct argument names. It is best to list each argument on a separate line. For example:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

The BDFL [Benevolent Dictator for Life] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it.

source: 〔Docstring Conventions By David Goodger, Guido Van Rossum. @ www.python.org…

there are quite a few interesting aspects.

CAPS for Parameters?

Note that in emacs's inline doc convention, function's formal parameters should be in CAPS in docstring. See: Emacs Function's Inline Doc String Markups. This isn't a great convention, because:

Newline at the End?

Guido's guide also suggests that the ending quote be on a line by itself. (that is, last char in docstring should be a newline char) Like this:

def f(x):
    """Something …
    x -- the arg.
    The End.
    """
    # 

On the other hand, emacs's convention tells people not to do that. Like this:

(defun f (x)
  "Something …
X is ….
The End."
  ;;   )

Again, Python's guide makes more sense. Because it's much easier to work with (when you edit and cut lines). Computers can easily add or remove such char when processing the docstring for rendering purposes or whatever purpose.

Line Length

another interesting point is that emacs's convention suggests using less than 67 chars per line. Python doesn't suggest this, but in practice, most lines are less than 80 chars per line because they need indentation at beginning of each line to make the left side aligned.

A better way is to not have line length limit, and newline char (␤) should be used for logical break only. Again, computer can trivially parse and truncate lines when necessary. It should not be a human burden. Also, limiting the use of ␤ for logical purposes makes it semantically meaningful. If ␤ is also used for formatting purposes, then parser won't be able to tell, thus losing parts of automation power.

blog comments powered by Disqus