[Top][All Lists]

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

Re: Re: imperative vs. descriptive style

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

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.


reply via email to

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