Check test docstrings

[ROpdebee]

Although your AAA blog post specifically mentions that the docstring is not a part of the AAA pattern, I quite like the guideline on writing positive, assertive docstrings. Maybe it's worth adding such a check to flake8-aaa?

It could be implemented as simple as testing the presence of the words "should", "will", or "when" in the docstring, or as complex as checking sentences against a predefined acceptable grammar such as

<subject> <acts> <outcome> [if <condition>]

E.g. "my_function raises ValueError if param1 is negative".

Maybe a negative assertive form should be allowed as well, in cases such as "my_nondestructive_sort does not modify its argument list", as opposed to "my_nondestructive_sort leaves its argument list unmodified". I feel like the first example reads a bit better and more clearly states that this behaviour is specifically not allowed to take place.

[jamescooke]

Thanks for this @ROpdebee 👍

I'm going to close this off because, as you mention, docstrings are not part of the AAA pattern. This linter is aimed at checking code rather than comments, so it's aiming to:

• Run as part of Flake8's linting run by processing the AST to check against the AAA pattern. I would prefer it not be tied to English docstrings, or do any language processing that's not directly in the AST / tokens.

• Build towards being able to have a partner formatter tool (like isort or Black) that will format tests so that they pass AAA linting. I'm struggling to see how a formatter could rewrite a failing docstring so that it passes the kind of rule you've outlined above without implementing some complex natural language processing.

However, I would be interested in contributing / reviewing if you or others decided to build such a checker. Feel free to comment further.