Re: imperative vs. descriptive style

[Jim Meyering]

On Sun, May 6, 2018 at 3:11 AM, Paul Eggert <address@hidden> wrote:
> Bruno Haible wrote:
>
>> The GNU Coding Standards [1] don't favour either, although I have vague
>> memories that 20 years ago, it advocated imperative style.
>
>
> Yes, I have the same vague memory, and still prefer imperative style in many
> cases. For routine use in comments, the imperative style is typically
> shorter and easier to understand. It's easier to read "Declare specific
> functions for X" than "This file declares specific functions for X", for
> example, and the longer wording does not convey enough extra information to
> justify its extra length.
>
> For specs that must contain qualifiers like "shall" or "should", the
> imperative style does not work well, and that's a good reason for POSIX and
> other more-abstract specifications to not use it.
>
> One other beef I often have with comments (including some that I write!) is
> that they are not sentences. At least this guideline *is* in the GNU Coding
> Standards.

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.