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/
