(Though a bit off topic, I'll put this back on the list as it's interesting to
(perhaps a few) other developers.)
Jim Blandy wrote:
> On 11/25/05, Julian Foad <julianfoad@btopenworld.com> wrote:
>
>>Minor syle point: we generally use the infinitive (subject-less) form of the
>>verb: "Translate the file" rather than "[This function] Translates the file".
>>(In English, the infinitive form is identical to the imperative (command) form,
>>if that makes it easier.)
>
> This is interesting. I had always considered doc strings to be
> written in the imperative. Since they're syntactically identical, why
> do you say they're in the infinitive? Is there some sense in which
> that's a better description of what's going on in a docstring?
It was just my assumption, I suppose, coupled with a feeling that I'd heard it
said before by someone. I think of the doc string as being implicitly prefixed
by something like "The purpose of this function is: [to] " + e.g. "Copy a file".
But now you mention it, when read from the point of view of the caller or the
interface designer rather than an onlooker, the imperative makes just as much
sense in that he/she/it is commanding the function to do certain things.
I think from now on I will sit on the fence and say something like "We write in
the imperative or infinitive (syntactically identical)".
In the Subversion mail archives I found no mentions of the infinitive, and
about two mentions of the imperative, and they were for descriptions of
Subversion commands in the book. It would be interesting to find out which the
majority of translators have chosen in languages where there is a syntactic
difference. (But not interesting enough for me to try to find out :-) )
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat Nov 26 11:12:55 2005