[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
policy.
- Changes in revision 114466, Eli Zaretskii, 2013/09/28
- Re: Changes in revision 114466, Xue Fuqiao, 2013/09/28
- Re: Changes in revision 114466, Eli Zaretskii, 2013/09/28
- Re: Changes in revision 114466, Thien-Thi Nguyen, 2013/09/29
- Re: Changes in revision 114466, Xue Fuqiao, 2013/09/30
- RE: Changes in revision 114466, Drew Adams, 2013/09/30
- Re: Changes in revision 114466, Stephen Berman, 2013/09/30
- RE: Changes in revision 114466, Drew Adams, 2013/09/30
- Re: Changes in revision 114466, Thien-Thi Nguyen, 2013/09/30
- RE: Changes in revision 114466,
Stephen J. Turnbull <=
- Re: Changes in revision 114466, Eli Zaretskii, 2013/09/30
- Re: Changes in revision 114466, Andreas Röhler, 2013/09/30
- Re: Changes in revision 114466, Eli Zaretskii, 2013/09/30
- RE: Changes in revision 114466, Drew Adams, 2013/09/30
- Re: Changes in revision 114466, Xue Fuqiao, 2013/09/30