[Top][All Lists]

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

Re: imperative vs. descriptive style

From: Bruno Haible
Subject: Re: imperative vs. descriptive style
Date: Sun, 06 May 2018 11:44:31 +0200
User-agent: KMail/5.1.3 (Linux/4.4.0-119-generic; KDE/5.18.0; x86_64; ; )

Hi Paul,

> * lib/af_alg.h: Use imperatives and tighten up wording.
> ...
> -/* Computes a message digest of the contents of a file.
> +/* Compute a message digest of the contents of a file.
> ...
> -   If successful, this function fills RESBLOCK and returns 0.
> -   Upon failure, it returns a negated error code.  */
> +   If successful, fill RESBLOCK and return 0.
> +   Upon failure, return a negated error number.  */

Whether to use imperative or descriptive style, is a matter of personal

The GNU Coding Standards [1] don't favour either, although I have vague
memories that 20 years ago, it advocated imperative style.

In comments outside of a function (targeted at the user of a function),
I find descriptive style more professional. Whereas inside a function
(in comments targeted at the implementor/maintainer of the function),
I find imperative style OK. It's a different perspective.

My taste is probably influenced by the fact that among the documentation
of major libraries, the majority are in descriptive style:
  - POSIX [2] (descriptive style with "shall" and "should"),
  - Java [3],
  - C# [4],
  - Common Lisp [5].

Only Python advocates imperative style ([6], search for "as a command"),
but that may be due to the fact that Python docstrings are written inside
the function. I.e. they don't know about the distinction "targeted at the
user of a function" vs. "targeted at the implementor/maintainer of the
function". (Which by the way is a pity for a object-oriented programming


[1] https://www.gnu.org/prep/standards/html_node/Comments.html
[2] http://pubs.opengroup.org/onlinepubs/9699919799/functions/unlink.html
[3] https://docs.oracle.com/javase/7/docs/api/java/lang/Object.html
[4] https://msdn.microsoft.com/en-us/library/system.object_methods.aspx
[6] https://www.python.org/dev/peps/pep-0257/

reply via email to

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