On Sun, May 6, 2018 at 3:11 AM, Paul Eggert <egg...@cs.ucla.edu> 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.
