[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: Changes in revision 114466

From: Stephen J. Turnbull
Subject: RE: Changes in revision 114466
Date: Tue, 01 Oct 2013 11:11:23 +0900

Drew Adams writes:

 > My (likely lone) opinion remains that there is rarely a good reason
 > to skip adding a doc string.

In this wide world you're not alone.  XEmacs policy has historically
been to put docstrings in everything that's "def'd" except for one-
line defsubsts and the like.  We also systematically convert leading
comments (and often comments where a docstring would go) to docstrings
more or less systematically.

On the other hand, many people (and the Emacs project, I believe) have
a policy of "docstrings document the API, if you want to know what
it's for or how it works, read the manual".  With good naming of
functions and parameters, often there is no need for a separate
description of the API.  Then the argument is that if you're going to
critically read the code anyway, the docstring means less lines of
code on screen.

I think you lose here on the basis that this is, pretty much, Emacs

reply via email to

[Prev in Thread] Current Thread [Next in Thread]