Hi Jim, > Perhaps it's because I have been writing deliberately imperative and > active-voice comments for so long that I find no ambiguity there.
Yes, 13 years ago, apparently I used this style as well. Nowadays I'm used to the descriptive style, because it is more established. [1] > I have made so many s/Returns/Return/ changes that I have a visceral > negative reaction to this change. Even in GNU, and specifically in Emacs Lisp, it's inconsistent: While the Emacs "Tips for Documentation Strings" [2] asks for imperative style, large parts of the Emacs Reference Documentation [3] have switched to "This function <descriptive style>". For example "This function returns t ..." [4]. > Perhaps as in those python guidelines, I do not think it is worthwhile > to use different writing styles/voices between header and non-header > files. Yes, function descriptions in non-header files (for 'static' functions) should be treated like function descriptions in header files, IMO. The real difference is: Am I talking to a user of the function? Or am I explaining the implementation details of the function? Bruno [1] http://lua-users.org/lists/lua-l/2012-03/msg00785.html [2] https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html [3] https://www.gnu.org/software/emacs/manual/html_node/elisp/index.html [4] https://www.gnu.org/software/emacs/manual/html_node/elisp/Symbols.html
