On 05/06/2018 10:33 AM, Jim Meyering wrote:
Here's the relevant section: (from
https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html)
Whenever possible, please stick to the active voice, avoiding the
passive, and use the present tense, not the future teste. For
instance, write “The function foo returns a list containing a and b”
rather than “A list containing a and b will be returned.” One
advantage of the active voice is it requires you to state the subject
of the sentence; with the passive voice, you might omit the subject,
which leads to vagueness.
Has it always been that way? I also have the vague recollection of RMS
telling people to write
Return a list containing a and b.
instead of
The function foo returns ...
or even
Returns a list ...
This imperative style is used in Emacs doc strings, which is probably
why I came to prefer it.
I agree it is somewhat of a personal preference, but probably worth
being consistent within a project, whatever style is selected.
jwe
