Re: Re: imperative vs. descriptive style

[John W. Eaton]

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