Automatically generate docstrings for your Python function | Hacker News Reader

Automatically generate docstrings for your Python function

github.com

24 pointsrcshubhadeep18 comments

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).

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.

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

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

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.

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"

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

It makes obvious that someone doesn't understand difference between code and documentation.

Or it makes it obvious the person is just learning the syntax and wrote themselves a reminder of what that weird ++ symbol means?

Why I need to guess? `i++ // ++ adds 1 to i` makes it obvious, instead of throwing your brain out of code parsing loop to decrypt the message.

The primary goal of documentation is to make code easier to understand, not to copy code or to puzzle the reader. If the documentation doesn't help, then it's useless, so it must be deleted, or it makes readability worse, so it must be deleted.

... and the response is to weed them out instead of educate?

Seems less pragmatic and more of a random death hill choice

Yes. The goal of grading is to grade students. If you need more education than other students, then look for a different profession or get a private tutor. Education system should not push squares into round holes with force. If a square doesn't fit a round hole, then let it go.

I'll admit that I immediately mistook 'fail' as - basically ensure they have no future in the program.

I'd be fine with points being removed or even perhaps a failed assignment - not being essentially outed from the program by failing the course. The student needs a chance to improve - otherwise the only thing they'll learn is resentment

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.

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.

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.

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.

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

Reply on news.ycombinator.com