The Value of Docstrings
summary
Argues that consistent Python docstrings (follow PEP 257) produce clearer, maintainable code by declaring behavior, args, return values and side effects next to the code. Demonstrates with a concrete sort_ducks example, shows using builtins like help() and tools like doctest to embed runnable examples and Sphinx to generate external docs. Claims docstring-driven development tightens encapsulation, guides naming, makes tests self-documenting, and that doctest-confirmed examples reliably stay correct as code evolves.
AI-written summary · about
chapters (32)
- 0:00Start
- 0:26About Me and Vanderbilt ACCRE
- 0:57But what about docstrings?
- 2:51Example Docstring
- 3:26Let's talk about comments
- 4:23Beginning to Code
- 5:11Basic Comments
- 5:35The play by play
- 6:32The metadata
- 7:16Inline change history
- 7:33Future plans
- 7:59Raw Emotion
- 8:14Other kinds of comments...
- 9:05Antithesis: To Comment
- 9:44Better Cleaner Code
- 10:40Naming is hard
- 11:04What property are we sorting on???
- 11:29Sorting Lotsa Ducks
- 11:54Are we sorting the list in place???
- 12:19Type hinting helps
- 12:51The halting problem
- 13:45Continuing to Code
- 14:59Synthesis: To Docstring
- 15:22Clean-ish code for an unclean world
- 15:52Writing more-or-less decent names
- 16:47Getting Your Ducks in a row
- 17:26Naming Hard, docstringing Easy
- 18:44Thoughtful Encapsulation - Doctrings or Underscores
- 20:31Docstring Driven Development
- 21:07Cleaner Code == Simpler Docstrings
- 22:41Sphinx - Generate Docs from Docstrings
- 26:30Some Concluding Thoughts
