[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
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/