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