D401 implementation is very naive

[adiroiban]

I have the following docstring.

    @property
    def file_path(self):
        '''Alias for consistency with the rest of pocketlint.'''

The error is

     142: D401: First line should be imperative: 'Alia', not 'Alias'

While the intent is noble, I think that the current implementation is not helpful.

Is there anyone using this check in production code?

If a check could not be done, I prefer to not try to automate it as it is not fun to maintain a list of ignored values..

Thanks!

[jacebrowning]

I have found this rule useful, but perhaps it should not apply to properties. All other method docstrings should be imperative (and I can't really think of any false positives), but property docstrings are typically not going to be imperative unless you do something like "Get the value of...".

[sigmavirus24]

Actually, this might read better as """An alias for consistency with the rest of pocketlint."""

[jacebrowning]

I found another good example of a false positive: """Focus the application."""

Perhaps pep257 could have a list of acceptable words that end in s?

[sigmavirus24]

A whitelist would be unmaintainable in my opinion @jacebrowning

[glennmatthews]

It could be interesting to investigate using NLTK (http://www.nltk.org/) here, although that would almost certainly be massive overkill.

[Nurdok]

I asked about this in English StackExchange: http://english.stackexchange.com/questions/216043/telling-if-a-word-is-a-verb-in-the-imperative-mood

[lordmauve]

This could be fixed by listing imperative forms of verbs and comparing with, say, a Porter stemmer (assuming English).

If the stemmed form of the word is in the stemmed list of verbs, then it's probably a verb. But if the unstemmed form is not in the unstemmed list, it's not in the imperative form.

This would have a much lower false positive rate than the current heuristic, but a somewhat larger false negative rate, depending on the size of the word list. But I'm guessing that relatively small lists of verbs would cover a high percentage of docstrings, due to the constrained nature of the language used (outside of domain-specific jargon).

We could generate a reasonably good word list by scanning docstrings of a few largish Python projects and manually removing words that are not imperative verbs.

[lordmauve]

Also it's out of scope to do a full grammar analysis, so we could never detect imperative or not in a docstring like

def median(xs):
    """Given a list of numbers xs, return the median."""

We could only flag up words that are verbs but not in an imperative form.

[lordmauve]

I started scanning my codebase for the verbs we use here. We could also add a blacklist approach - there are words that are very much indicators of non-imperative docstrings.

[lordmauve]

Can this issue be closed, now #235 is merged?

[Viech]

I think this issue should be reopened as #235 does not seem to affect the general case where a method decorated with @property is requried to be in imperative mood. So while Alias might be treated as a potential imperative now, properties are still not allowed a docstring starting with words like The or A.

[josauder]

Large neural network language models such as GPT-3 open up completely new possibilities to check if a sentence is in imperative mode. Maybe this should be added to this project.

I don think this would impair productivity even more than attempting to check if docstrings are in imperative to begin with.
@bjrne

[lukelbd]

I'd also support reopening this. Imperative mood checking is a very promising feature but enforcing it for @property "functions" forces me to ignore all D401 errors.

[CountingBeeps]

I would too. Or at least allow "The" or "A" for them.

[lordmauve]

Please open a new issue if you think D401 should not apply to @property functions*. That is not the issue that was addressed here.

* But I would argue it should because if you allow a noun phrase for the getter what do you write in the docstring for a setter or a deleter?

[merwok]

You don’t write docstring for them :)

[lukelbd]

I've started a new thread: #566.