The Imperative Style in Commits and Docstrings

& (verbiage overflow) ⋅ ⋅ Fri 18 October 2013 ⋅ RSS

I wrote earlier about grammatical tense in Git commits, but have been thinking more about it today. My inclination has always been to make a commit message a description of my own actions in relation to my code or the state of the project:

updated database

fixed all remaining bugs; README still skimpy

refactored main() to find & use most current dump

etc.

But as I described in the earlier post, I was surprised to find that there is widespread and competing advocacy of the principle that we should write in either present tense or imperative mood.

Present tense and imperative mood are not the same thing, and if you read actual examples from around the Web, you quickly find that prescriptions and implementation of commit-grammar vary quite a bit. GitHub seems to advocate using present or simple past tense:

If you make a commit in a non-default branch with the “Fixes #33” syntax, the issue is referenced with a tooltip.

You can use any of the following keywords to close an issue via commit message:

(https://help.github.com/articles/closing-issues-via-commit-messages; cf. http://gitref.org/basic/#commit, which does not discuss issues of grammar at all; both accessed 20131018)

Drupal advocates past tense:

Usually, commit messages start with the (past tense) verb

It may not be trivial to phrase a summary starting with one of those verbs. But if used consistently, you will get used to it. When not using these verbs, make sure you prefix the commit message with the issue category. (https://drupal.org/node/52287, accessed 20131018)

Erlang advocates using a command:

Write the summary line and description of what you have done in the imperative mode, that is as if you were commanding someone. Write “fix”, “add”, “change” instead of “fixed”, “added”, “changed”. (https://github.com/erlang/otp/wiki/Writing-good-commit-messages, accessed 20131018)

Python officially prescribes using commands:

The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command (“Do this”, “Return that”), not as a description; e.g. don’t write “Returns the pathname ...”. (http://www.python.org/dev/peps/pep-0257, by David Goodger and Guido van Rossum, accessed 20131018)

I don't see prescriptions for Ruby, Java, or C++. The discussion of GNU change-log style doesn't seem to have any English syntax in mind.

The Erlang and Python model is so strange, and so insistent about avoiding the more natural practice of simple description, that it requires adding some energy in order to understand what is going on.

What makes the use of a command in a commit-message or docstring unsettling is trying to see how it relates to the use of the commit or function it goes with. (A commit can be understood as a kind of function acting on one's repository, so from now on I'll refer only to functions and docstrings.) A command implies direction, instruction, exhortation, or persuasion. As a matter of grammar, imperative mood takes a number of forms — the second person (“you”) form is most familiar in English, where the speaker tells the hearer or reader what to do:

Go away!

Give that grain of rice back back to the farmer you got it from at once.

Don't even think about parking here.

etc.

It may seem strange for exhortation or direction to be operating when we use a function. Who is exhorting whom here?

In a computer program a function is ultimately an event and a process, even in most languages that are organized on functional or object-oriented principles. The docstring serves as a description of the effect of that process. If we read a docstring as a second-person command, we can take it to be directed not at the function itself (directing it to act in a certain way) but at the processor that carries out the function.

We should imagine directives being passed imperatively (“You do this…”) from the program to the CPU. I think that is the most plausible psychology of the docstring grammar prescribed by the Erlang and Python camps.

But as I have found by looking around, this is far from universal practice in commit messages and docstrings generally.

[end]

Comments are enabled.