|
From: | John W. Eaton |
Subject: | Re: Re: imperative vs. descriptive style |
Date: | Mon, 7 May 2018 09:46:25 -0400 |
User-agent: | Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.6.0 |
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
[Prev in Thread] | Current Thread | [Next in Thread] |