Re: imperative vs. descriptive style

[Bruno Haible]

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
style.

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
language.)

Bruno

[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
[5] 
http://www.ai.mit.edu/projects/iiip/doc/CommonLISP/HyperSpec/Body/stagenfun_all_ate-instance.html
[6] https://www.python.org/dev/peps/pep-0257/