[Top][All Lists]

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

Re: imperative vs. descriptive style

From: Jim Meyering
Subject: Re: imperative vs. descriptive style
Date: Sun, 6 May 2018 07:33:07 -0700

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

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.

reply via email to

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