Docstrings: Imperative or indicative mood?

Internals & Design
1
Whether this is the best place for this topic is a little muddy, #dev:internals is a “best guess” from me, mostly from it not fitting cleanly into General Usage.

I’m currently putting together docstring linter, that goes beyond checking that public functions have docstrings to also perform checks like:

  • Signatures actually match the function being documented
  • All arguments in the signature are mentioned in the docstring
  • Paragraphs consist of complete sentences.
  • Docstrings start with a brief summary line.
  • etc.

As part of this, I’m also checking whether verb voicing is imperative or descriptive. I think it’s worth pushing people to one style for consistency, but I’m not sure which is best.

Imperative mood

In the imperative mood, docstrings are a complete sentence that’s written as an instruction the computer follows.

Examples

  • “Return the number of widgets in a set.”
  • “Control access to the phlebotinum.”
  • “Set the printer on fire.”

Advantages

  • Clarity/conciseness: the imperative mood tends to be more direct and to the point.
  • It’s grammatically a complete sentence, with no implicit subject.

Drawbacks

  • Perceived abruptness
  • Potential misinterpretation of the target of the directive (the computer)

Indicative mood

When the indicative mood is used with docstrings, the subject is implied, rather than explicit — forming an adjectival phrase rather than a complete sentence.

Examples

  • “[This function] returns the number of widgets in a set.”
  • “[This type] controls access to the phlebotinum.”
  • “[This module] sets the printer on fire.”

Advantages

  • More natural language flow: most people naturally describe things indicatively
  • Flexible expression: an indicative mood accommodates a broader variety of sentence structures

Drawbacks

  • Implicit context/grammatical issues: the description is an incomplete sentence with a dangling antecedent.
  • Potential verbosity/stylistic inconsistency

Related links

Choice quotes

Some of this reading has me leaning more towards pushing for an imperative style. Here are two particular excerpts:

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.

[With an imperative style] international contributors don’t have to do as much work to figure out if a simple present conjugation of a verb is irregular as it would be, for example, with the verb “to go”. The correct conjugation with my approach would be “Goes”, but English is weird so maybe let’s just be kind and let people use the simple unconjugated verb “Go” to start the docstring.

A poll

What do you think? I’d be interested in hear thoughts, as well as conducting a strawpoll on preferred grammatical mood.

Preferred docstring mood
  • Imperative mood
  • Indicative mood (descriptive)
0 voters
2

I used to prefer the indicative mood. It was for no apparent reason; it just felt natural to me. I then learned that the imperative mood should be used in the Julia’s code base (I think I read it in some issue on Github or somewhere), so I started using that, and now I prefer the imperative mood.

I voted for the imperative mood in the poll, but in the end I wouldn’t mind the indicative mood either. It would be nice if one of them was used consistently everywhere, though.

By the way, how are you going to check the mood in your linter? I am curious.

3

The Julia manual recommends imperative mood:

The one-line sentence should use the imperative form (“Do this”, “Return that”) instead of the third person (do not write “Returns the length…”) when documenting functions.

So let’s go with that.

4

Ah, the manual already mentions mood! Brillant, I didn’t think to look.

It also occurs to me that docstrings probably count as “reference” documentation under the venerable Diataxis framework, and its suggestions around reference documentation seem to align more with the imperative mood.

Reference material describes the machinery. It should be austere. One hardly reads reference material; one consults it.

Unfortunately one of the hardest things to do is to describe something neutrally. It’s not a natural way of communicating. What’s natural on the other hand is to explain, instruct, discuss, opine, and all these things run counter to the needs of technical reference, which instead demands accuracy, precision, completeness and clarity.

5

I’ve stolen a list of common verbs :wink: (from Emacs’s checkdoc-common-verbs-wrong-voice)

6

This is a super nice initiative! Following some ideas in JuMP, I recently experimented with vale.sh a bit, which I could (for a while) convince to lint my doc strings, but that broke again in their version 3.5; so improving style / writing in doc strings is something I would love to see more support for in Julia!

I voted for the indicative mood, since that is what I am used to. To me the imperative mode sounds a bit like the user is expected to do that, but that might be me being non-native-english speaker (German mother tongue).

7

Yeah, very long ago I found out the Julia manual recommends imperative and I’ve went ahead and wrote all the docs I maintain in this style… I don’t think it matters much, but what matters most is coherence, so since one has already been established I think it is best to go with that :slight_smile:

8

I use a slight variation of the “recommended” style, consisting of three elements:

  • a “title” (a single-sentence summary of the function in imperative style)
  • the code block with the function signature
  • one or more paragraphs in the descriptive style. This continues the code block, as a sentence.

For example,

"""Optimize a quantum control problem.

```julia
result = optimize(
    problem;
    method,  # mandatory keyword argument
    check=true,
    callback=nothing,
    print_iters=true,
    kwargs...
)
```

optimizes towards a solution of given [`problem`](@ref ControlProblem) with
the given `method`, which should be a `Module` implementing the method, …

for QuantumControl.optimize.

One reason is that at some point (maybe with a Documenter plugin), it might be nice to surface the summary of functions, like in the docs of one of the Python-precedents of QuantumControl.

As far a linters go, I’d like a linter to be able to enforce that particular style :wink:

9

I’ll open another discussion for general rule-bikeshedding later (maybe use the eventual [ANN] thread for that? Feel free to open issues in the repo too), but I’ll mention that the Julia manual that Jakob so kindly linked earlier already prescribes a summary line after the signature:

    func(args...; kwargs...)

Summary line written in an imperative style.

A more complete description of the behaviour, arguments,
etc.

You seem to have (to me, weirdly) shuffled the first two elements around, but we can indeed use that initial summary line in the way you link so long as people embrace/conform to it enough.

10

the Julia manual […] already prescribes a summary line after the signature

Yes… there’s style recommendations in the Julia manual that I disagree with. Some of them very strongly: “multiple words squashed together” – seriously? Anyway…

I find having the summary line easier to find in the source code if it’s the first line, so I don’t have to visually parse for the end of the code block. I also find it a natural way to switch from the imperative to the descriptive tone. But sure, this is a matter of taste. Especially since, right now, there isn’t any tooling to actually do anything with summary lines.

Opened an issue: Check for summary lines before or after signature · Issue #9 · tecosaur/CheckDoc.jl · GitHub

11

Don’t get me wrong, I think it is great when people pay close attention to minor things like this. But as a package user, I am happy with finding documentation in any mood, including “grouchy”.

Consequently, I don’t think anyone outside an organization or group of authors should be “pushing” people too much about the grammatical mood of package docs, as I am concerned that nitpicking like this will just make people even more reluctant to write docs.

As a package maintainer, I am happy to accept doc PRs in whatever mood they come and would not dream of making a suggestion to correct anything.

12

We are talking about automation here to the best of my understanding. I don’t share your concerns on this topic as automation shouldn’t be hurting anyone’s feelings.

(I also don’t share the pessimistic tone that seems to imply that things are barely ever documented; that’s not my impression so far in the Julia land. But that’s another discussion)

In the opposite, I always make a suggestion to correct tone so that the docs are harmonious. In my experience no-one has ever been dissuaded by that. Do you have experience of improving the harmony of someone’s contribution and they telling you “please stop”, or something? I find it difficult to imagine because this topic is actually pretty objective. Sure, your preference is subjective, but that your doc contribution should have the same style as the rest of the document is a pretty subjective and straightforward thing to resolve.

13

Unfortunately, yes. Or people abandon PRs because they perceive it as too much effort to contribute docs changes. Granted, this seems to be more of a problem for longer passages and not one line changes.

14

I’d also like to point out that if somebody PRs a docstring in the “wrong” grammatical mood, saying that you can:

  • Nitpick their PR, or
  • Resign yourself to a mix of moods

draws a false dichotomy. There’s a third option I’d like to present (and that IMO should be chosen in general more often, especially for new contributors):

  • Mention what matches the project style, accept the PR anyway, and then commit a tweak/fixup on top
15

Since Julia itself often ignores its own recommendation to use imperative style, I think we shouldn’t take it seriously. In addition, I’d be more likely to use your package if it didn’t annoy me about issues I don’t care about.

16

If you want to check your docstrings but don’t like certain rules, just run it without those rules :person_shrugging:. I think it’s worth encouraging as much consistency as can reasonably be asked for by default though.

17

Well, first and foremost I’m happy to read documentation in any consistent style, but personally I tried to write docstrings in the recommended imperative mood but gave up.

The semi-rational reason: Oftentimes it is necessary to additionally write what the function does in some specific conditions, like,

for bar<0, foo returns nothing

Sure, it is possible to put it each time into imperative, but it is not the normal speech flow - how often do you pronounce several sentences in succession with all verbs in the imperative mood (and that without a single “please” :stuck_out_tongue_winking_eye:)? On the opposite, if you in your docstrings write what a function does with this or that argument, you would probably use exactly the same words to explain it in a discussion with a colleague.

The less-rational reason: I somehow feel it strange to command - to what? to whom?

I have multiple gripes with this text. First, “international contributors” is implicitly USA-centric, as it implicitly opposes “us” (national contributors) to “them”. Second, it insinuates “they” are generally not able to learn the basics of English. Third, “let’s be kind [to them]” sounds condescending. Fourth - has anybody tried to find out what international contributors non-native English speakers would actually prefer? I guess it might correlate (in my case, it does!) with how such a phrase would be built in their native languages.

I’ve tried to check Python documentation in different languages. In English, it is imperative, sure. In my native Russian, it is in indicative: Imperative would be possible but sound strange. For German, I was happy to find nothing. Of many languages listed in 3.13.0 Documentation , I have only rudimentary knowledge of Italian - but I guess it is indicative there.

In short: Would it be possible to have optionally both styles in your linter? In consideration of the substantial minority preferring indicative mood.

18

This is how I’ve put it in the current doc linter info-message:

“Think of it as describing the action of the function as a command the user gives to the computer by calling the method.”

For example, by calling mv("a.txt", "b.txt") you’re telling the computer to “Move file a to b”.

Interesting, thanks for mentioning this.

Sure! It’s perfectly reasonable for individual projects to make deliberate changes from the general recommendations. I might ask people to PR rules that they’re more interested in having than I am though :stuck_out_tongue: (happy to help though).

The doc checking API itself is fairly flexible, e.g. here’s running a suite of checks without the imperative checks:

checkdoc(MyMod, setdiff(CheckDoc.LEVEL5,
                        [Checks.Style.Summary.ImperativeMood,
                         Checks.Style.Summary.ImperativeOpening]))
19

Usually I do not (yet) talk to my computers. You know - “you shouldn’t anthropomorphize computers - they don’t like it.”

20

This is not about feelings, personal cost/benefit analysis of contributing. Contributors may just quietly disappear if you make them jump through too many hoops for no good reason. Again, this is just me, but if I had to edit my otherwise perfectly understandable text just to please a robot, I would abandon it unless I really care about the project.

I don’t think that enforcing consistency in this particular domain adds any value to documentation. Personally, I don’t care if the grammatical mood of docs is consistent for any software I use, as long as the meaning is clear. I might even prefer a slight variety in the style of docs, within bounds, as it may be less dry to read.

But note that I am the kind of person who finds it entertaining to read a monograph written about a subject by a bunch of different authors, and relish their various perspectives and styles.