Hacker News Reader

Comment by julienpalard | Hacker News Reader

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

View on HN

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.

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.

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.

Reply on news.ycombinator.com