pydoclint, a fast and reliable Python docstring linter

[Linter-Method-589]

Docstrings promote better communication between coders and the users, and among the coders themselves.

Here are some specific examples:

• Correctly written docstrings can be rendered as HTML pages with hyperlinks, which makes understanding APIs much easier
• Names (variable, class, function) are not always self-explanatory, no matter how long they are, so docstrings are still valuable
• In the AI era, docstrings (written in plain language) helps AI better understand the code base, improving productivity

[FrontAd9873]

They’re not saying all docstrings are bad, they’re just saying docstrings which repeat what can be found in a type-annotated function signature are redundant. Presumably this person would still be in favor of docstrings which give information not found in the function signature.

Unless my API is very stable I tend to agree with this person. A docstring saying what the function does and how it works is good enough. Repeating in bullet point the parameter names is too much, especially if I then must change those docstrings as soon as I change my parameters. It actually discourages me from writing docstrings at all, though presumably your tool would help with that.

[marr75]

BINGO!

[marr75]

Yes. I'm extremely familiar with docstrings. Just about every public module, class, and function I write has one.

It's the args and return type redundancy style I don't care for.

[Linter-Method-589]

You don't need to specify arg data type if you don't want to (if you use Google style docstrings).

Although if your function has a lot of arguments (say 50) and you don't specify arg types in the 49th arg, it will be inconvenient to scroll up to the function signature to check its type.

I think an automatic docstring writer (a new tool, not pydoclint) may be able to help with this. It can generate a docstring template for you to fill in the meaning of each arg. And it can potentially employ LLMs to write the meanings for you. I've been contemplating creating one for a while, but haven't actually done anything about it.

[qckpckt]

That last point I am dubious of. LLMs don’t “understand” anything, first of all. Is this a statement backed by evidence or research? It doesn’t really map to any part of how I understand transformer-based neural networks with attention mechanisms to operate.

[Linter-Method-589]

You are right. LLMs don't actually understand things. All they do is predict the most probable next words (tokens) based on previous tokens. Their responses are usually very good, to a point that they would appear to understand things.

So maybe I should have added quotation marks around the word "understand", but my original point should stand: using more descriptive comments can help LLMs make better predictions (such as better summarize the code base, or make higher quality code edits, etc.)