Automatically generate docstrings for your Python function

by rcshubhadeep • 4 years ago

24 18 4 years ago

This is typically the kind of idea that I don't understand: docstrings are here so the developer can state what *needs* to be stated here (the *not obvious*) the why, the how, the known limits...

Taking a comment as an example, compare:

    if is_even(x):  # if x is even

and:

    except UnicodeError as err:  # Can happen on malformed IDNA.

One is not usefull (but can be derived automatically), the other one IS usefull to understand the code, but *can't be derived automatically* (without a deep understanding of the used libraries behind the various calls in the try statement).

kqr• 4 years ago

I can see one useful case for this type of software: you want to apply a lint rule that says "all functions must have docstrings".

With this tool, you can programmatically add a dumb docstring to everything to make the linter shut up about old code, and still have it complain about new code.

Of course, some sort of ratcheting in your build pipeline would be better.

satya71• 4 years ago

Linter shutting up should be handled at linter level, not by mechanical additions to code.

drran4• 4 years ago

So, you want to put spam into code comments? Why not to put affiliate links then.

teknopaul• 4 years ago

Word. I call them SBO comments (stating the bleeding obvious) and prune them from code.

Pretty much all doc gen tools can generate is SBO comments so they are rarely useful.

Often they are essentially wrong, e.g. a getter with the autogenerated comment "gets the X from Y" without checking the method code to see if actually, it has some horrible side effects that you would not expect to be there. The comment hides the truth about the method.

ratdragon• 4 years ago

Basic programming course teacher on uni told us that if we ever make such an obvious comment/docstring we'll be failed at the speed of light, no second chances.

His example was: "i++ // add 1 to i"

omnicognate• 4 years ago

What an absurd reason to fail someone in a basic programming course.

patrick451• 4 years ago

With doc strings, a lot of this is driven by linters that require you to write a doc string. People are in a hurry and don't like writing documentation, or what the function does just seems obvious, so they throw a doc string together that just rewords the function name and its arguments into passable English so the linter will shut up.

This is just one of many ways that running tools like pylint in CI can make your code worse.

rufasterisco• 4 years ago

Docly is not maintained anymore. Codist is in the process of shutting down. Sorry for the inconvenience

mkl952• 4 years ago

I don't think it's a great idea. But it would be with a focus on AI. A tool that analyzes source code and attempts to give a high-level explanation of how it works would be powerful.

qayxc• 4 years ago

Now that would be something I'd be seriously impressed with.

It would make maintaining, bug fixing, and auditing complex software systems so much easier. It'd be a true game changer.

mkl952• 4 years ago

Onboarding as well. Many companies lack proper documentation and the resources to answer complicated questions, so new devs are expected to figure things out. It takes them several months to properly grok how the different modules of some SaaS interact with each other, and their major quirks. Chances are by the time the new dev understands the system, they have made several bad decisions that have made it to production and are not trivially reversible. With a tool that gives a rough description of how things work and what parts of the system are the most vulnerable, the effort would be reduced to proof reading and some manual additions by some experienced team members.

Automatically generate docstrings for your Python function

Related Stories