"The Value of Docstrings" - Eric Appelt (Pyohio 2019)

Описание: Eric Appelt

https://www.pyohio.org/2019/presentat...

Python docstrings differ from regular comments in that they are stored
as an attribute of a callable object and are accessible through the
help() builtin function. However, their importance in writing
readable and maintainable python modules has very little to do with their
technical language features in Python, and much more to do with the
discipline they bring to effective documentation.

Any new developer will encounter well reasoned advice on the need to
comprehensively comment their code, and contrary but equally reasonable advice
to avoid using comments at all by writing better code. This talk will briefly
explore these viewpoints, and then review the standard conventions for Python
docstrings. I argue that the consistent and conventional use
of Python docstrings results in more readable and maintainable code than
that written with only unstructured comments, independent of how sparse or
plentiful those comments may be.

Additional areas of improvement in software design are discussed, including
effective encapsulation, the difficulty of naming methods, "docstring driven
development", extension into external documentation, and integration with testing.
Finally, I argue that Python
docstring conventions are a model for improved software design in general,
and are worth adopting even in other languages that do not necessarily
support actual docstrings.

Docstrings are a common convention in Python programming, but
their value may be taken for granted. In the absence of docstrings, schools of thought on writing effective code involve using many comments or using few if any comments. I will
argue that docstrings improve upon these approaches, and then explore how they can positively impact encapsulation, testing, documentation, and design.

===
https://pyohio.org

A FREE annual conference for anyone interested in Python in and around Ohio, the entire Midwest, maybe even the whole world.

Produced by NDV:    / @nextdayvideo  

Sat Jul 27 15:45:00 2019 at Barbie Tootle