Phython: missing-function-docstring (pylance)

Question

Im getting the message from pylace at my function. What to do?

def retangulo(larg, comp):
   
    area = larg * comp
   
    print(f'A área de um terreno {larg} x {comp} é {area}.')

docstringpylint(missing-function-docstring)

I am expecting to understand how to write python the "right way".

Asked By: Renan Soares

||

Source

Answer 1

… write python the "right way".

That is certainly commendable.
Not sure I’d want to insist on a """docstring""" on
every function though, since some, like this one,
are already pretty self-explanatory.

The missing-function-docstring diagnostic is inviting you to add a single
sentence of documentation, such as this:

def retangulo(larg, comp):
    """Displays the area of a rectangle, given its two sides."""
    area = larg * comp
    print(f'A área de um terreno {larg} x {comp} é {area}.')

Consider linting with flake8 instead.
It is not too picky.
When I find it complaining,
I usually agree with its complaint,
so I fix things up at once to ensure it remains silent.

Consider running black . before linting,
to automatically fix up minor whitespace issues.

Consider throwing in an optional type hint or two:

def retangulo(larg: int, comp: int) -> int:

Remember that python does not do any runtime
checking / enforcement of types,
so retangulo(1, math.pi) would still "work".
The mypy static analysis checker
would dutifully complain about such a call.

Or, since the concepts of length and area
are defined across non-negative real numbers,
it would no doubt be better to declare like this:

def retangulo(larg: float, comp: float) -> float:

You don’t have to use type hints,
and if you do you certainly don’t have to use
them everywhere.

But in addition to their concise documentation
value to humans, and the linting value of a mypy run,
they can play very nicely with IDEs, such as PyCharm.
When you type foo. CTRL-SPACE and hope to see
some auto-completion suggestions, the type of foo
matters. And hints help the IDE to make
relevant suggestions.
For example, if the IDE knows that foo is a regex,
it might suggest .findall( as a completion,
which is quite different from what it would
do with a str variable.

Answered By: J_H

Phython: missing-function-docstring (pylance)

Question:

Answers: