Real Python
realpython.com › documenting-python-code
Documenting Python Code: A Complete Guide – Real Python
July 17, 2026 - You can also tell that the expected output of the function will be of a type str, or string, as well. While type hinting helps reduce comments, take into consideration that doing so may also make extra work when you are creating or updating your project documentation. You can learn more about type hinting and type checking from this video created by Dan Bader. ... Now that we’ve learned about commenting, let’s take a deep dive into documenting a Python code base.
Python How Tos
campbell-muscle-lab.github.io › howtos_Python › pages › documentation › best_practices › best_practices.html
Documentation Best Practices - Python How Tos
If the function doesn’t return anything, don’t add a Returns section. The Raises section is for documenting any errors the function might raise if any problems are encountered during its executation.
What are your preferred conventions for documenting python code?
Module docstrings. I don't think I've ever worked with someone else who writes them. Open up a file for the first time, see 30 lines of imports and a bunch of functions that call each other, the file name is generic and provides no context. This tier of missing documentation is really painful. Just explain what should be used outside the module, specific terminology used here and how things link together. I'm tired of building up the design in my mind from all the implementation bits. More on reddit.com
20
22
December 7, 2022Advanced python tips, libraries or best practices from experts?
Some ideas, might be obvious but I list them here anyway: Project design and setup Decide for a licence Automate tests and deployment with CI/CD If it's open source, think about how others can contribute. Know your target groups Learn to write documentation. Your best fancy, sophisticated code is incomplete if you can't explain what your project does. Explain it to your target groups. An API documentation is NOT a replacement for a user guide. Use a modern Python environment/packager like uv Check out if you can use pyproject.toml Source code and design Keep your source code format consistent or use blake or ruff to format it. Never mix tabs and spaces Document your code with docstrings Name your objects consistently Use type annotations Modularize your code (separation of concerns) Never show exceptions to the user Use logging Use classes when you really need it. Don't overuse it if you can do the same thing with functions. Check out dataclass, enum, and others in the standard library Learn to write decorators Learn to understand design patterns Write tests, but also know how and when to use it and when not We could write more to each item, but that's enough for now. 😉 Good luck! More on reddit.com
71
153
October 18, 2024What is the best practice for __init__ with many arguments?
I'm a beginner but wouldn't it be better to have those dozen lines laid out nice and readable rather than trying to compress everything into less lines and end up making it less maintainable? It seems like one of the points of using classes is to have nice and neat structured code. So, I would think making the class structure itself very clear would be the way to go. More on reddit.com
42
12
October 16, 2013What's your opinion on what to include in __init__.py ?
I tend toward option 3 for my own work. For me, it's about declaring a 'public' API for the module, e.g. stuff/ __init__.py bigstuff.py privateStuff.py And __init__.py would have: from bigstuff import Stuffinator, Stuffinatrix This essentially says that stuff.Stuffinator and stuff.Stuffinatrix are the only parts of the module intended for public use. While there's nothing stopping people from doing an 'import stuff.bigstuff.Stuffometer' or 'import stuff.privateStuff.HiddenStuff', they'll at least know they're peeking behind the curtain at that point. Rather than being implicit, I find it's rather explicit. More on reddit.com
50
128
March 30, 2013What Is Documentation in Python?
Documentation in Python refers to the written text that accompanies a Python software project. This text explains the purpose and use of the code, making it easier for others (and often yourself in the future) to understand and maintain. Python documentation can come in many forms, from inline comments and docstrings within the code itself, to external documentation like user manuals and API references. Python is particularly well-suited for good documentation practices due to its clean, readable syntax and strong support for docstrings—in-code explanations of functions, methods, and classes.
swimm.io
swimm.io › learn › code-documentation › documentation-in-python-methods-and-best-practices
Documentation in Python: Methods and Best Practices - Swimm
Best Practices for Documenting Python Code
Write Clear and Concise Docstrings A good docstring should be clear, concise, and informative. It should quickly convey what the function does, without going into too much detail. Avoid jargon and complex language—your goal is to make the function's purpose understandable to anyone who reads the docstring. It's also good practice to include information about the function's inputs, outputs, and any exceptions it might raise. If your function has side effects (i.e., it changes some state outside its own scope), be sure to document these as well. Include Examples in Documentation Examples are a p
swimm.io
swimm.io › learn › code-documentation › documentation-in-python-methods-and-best-practices
Documentation in Python: Methods and Best Practices - Swimm
4 Ways to Document Python Code
1. Inline Comments One of the simplest ways to document your Python code is through inline comments. These are brief notes written directly into the code, typically on the same line or directly above the code they refer to. Here is the syntax for comments in Python: Inline comments are great for explaining the rationale behind certain code decisions, or for providing a quick summary of what a complex piece of code does. However, it's important to use inline comments judiciously. Overuse can clutter the code and make it harder to read. As a general rule, your code should be self-explanatory. U
swimm.io
swimm.io › learn › code-documentation › documentation-in-python-methods-and-best-practices
Documentation in Python: Methods and Best Practices - Swimm
03:13
Python - Function Documentation using docstring and help() - Code ...
01:30
Documenting a Function in Python: DOCSTRING in Python - Python ...
05:50
#6: Python Docstrings | Python Best Practices - YouTube
02:30
[ Python Best Practices ] - How to document python functions? | ...
Reddit
reddit.com › r/python › what are your preferred conventions for documenting python code?
r/Python on Reddit: What are your preferred conventions for documenting python code?
December 7, 2022 -
The method of documentation I learned in school is to list a function name, description, parameters, return type, and exceptions. It's serviceable, but a tad verbose and prone to redundancy. What do you recommend?
I am documenting the code for my new password manager. Here is the source on Github.
Top answer 1 of 7
11
Module docstrings. I don't think I've ever worked with someone else who writes them. Open up a file for the first time, see 30 lines of imports and a bunch of functions that call each other, the file name is generic and provides no context. This tier of missing documentation is really painful. Just explain what should be used outside the module, specific terminology used here and how things link together. I'm tired of building up the design in my mind from all the implementation bits.
2 of 7
10
Personally I like the google format docstring (see section 3.8) .
Python
peps.python.org › pep-0008
PEP 8 – Style Guide for Python Code | peps.python.org
Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does.
The Hitchhiker's Guide to Python
docs.python-guide.org › writing › documentation
Documentation — The Hitchhiker's Guide to Python
In Python, docstrings describe modules, classes, and functions: def square_and_rooter(x): """Return the square root of self times self.""" ... In general, follow the comment section of PEP 8#comments (the “Python Style Guide”). More information about docstrings can be found at PEP 0257#specification (The Docstring Conventions Guide). Do not use triple-quote strings to comment code. This is not a good practice, because line-oriented command-line tools such as grep will not be aware that the commented code is inactive.
Docuwriter
docuwriter.ai › home › blog › essential function documentation in python: a guide
Essential Function Documentation in Python: A Guide | DocuWriter.ai
April 3, 2025 - Regularly review and update your documentation as your code changes, ensuring it stays a valuable resource. This proactive approach prevents documentation from becoming a burden, reinforcing its value in any successful Python project.
Docuwriter
docuwriter.ai › home › blog › python documentation best practices: a complete guide for modern development teams
Python Documentation Best Practices: A Complete Guide for Modern Development Teams | DocuWriter.ai
December 20, 2024 - Unlike regular comments, they provide structured, executable documentation that integrates directly with your code. When writing Python modules, classes, functions, or methods, clear docstrings help other developers understand and use your code correctly without digging through implementation details.
Dataquest
dataquest.io › home › blog › how to use python docstrings for effective code documentation
Tutorial: Documenting in Python with Docstrings
December 13, 2024 - Finally, all functions should be properly documented as described previously. Here, I omitted the "Arguments" and "Returns" descriptors because, from my perspective, they're unnecessary. Also, note how I used the code comments and how they are different from docstrings. If you have a script you wrote, add to it some documentation to practice. It should be pretty clear why documentation is important and why docstrings are an essential part of Python documentation.
DataCamp
datacamp.com › tutorial › docstrings-python
Python Docstrings Tutorial : Examples & Format for Pydoc, Numpy, Sphinx Doc Strings | DataCamp
February 14, 2025 - They are used to provide documentation for Python modules, classes, and methods, and are typically written in a specialized syntax called "reStructuredText" that is used to create formatted documentation. In Python, you can access a docstring using the __doc__ attribute of the object. For example, you could access the docstring for a function using my_function.__doc__or the docstring for a class using MyClass.__doc__. No, docstrings are not required in Python. However, they are part of the best practices for documenting your code.
Swimm
swimm.io › learn › code-documentation › documentation-in-python-methods-and-best-practices
Documentation in Python: Methods and Best Practices - Swimm
November 5, 2024 - Python is particularly well-suited for good documentation practices due to its clean, readable syntax and strong support for docstrings—in-code explanations of functions, methods, and classes.
Lsst
developer.lsst.io › v › DM-5063 › docs › py_docs.html
Documenting Python Code — LSST DM Developer Guide latest documentation
A one-line summary that does not use variable names or the function name: def add(a, b): """Sum two numbers.""" return a + b · The summary should be written as a present-tense action. Do not write something like “Sums two numbers.” · The one line summary can be used alone only in extremely ...
Docuwriter
docuwriter.ai › home › blog › python documentation best practices: a comprehensive guide
Python Documentation Best Practices: A Comprehensive ...
November 15, 2024 - Learn how to write effective Python documentation using docstrings, inline comments, type hinting, and documentation generators like Sphinx. Improve code readability, maintainability, and collaboration with these best practices.
CodeRivers
coderivers.org › blog › python-function-documentation
Python Function Documentation: A Comprehensive Guide - CodeRivers
February 22, 2026 - This makes it easier for developers to read and understand the documentation. For example, if you start using a particular format for documenting parameters in one function, use the same format throughout. Sphinx is a popular tool for generating documentation from Python docstrings.
Readthedocs
sphinxcontrib-napoleon.readthedocs.io › en › latest › example_google.html
Example Google Style Python Docstrings — napoleon 0.7 documentation
""" def __init__(self, msg, code): self.msg = msg self.code = code class ExampleClass(object): """The summary line for a class docstring should fit on one line. If the class has public attributes, they may be documented here in an ``Attributes`` section and follow the same formatting as a ...
Compile N Run
compilenrun.com › python tutorial › python best practices › python documentation
Python Documentation | Compile N Run
By following these best practices, you'll create code that's more maintainable, easier to collaborate on, and more professional. ... Take a previously written Python function and add a proper docstring following Google style conventions. Set up ...
Python Developer's Guide
devguide.python.org › documenting
Getting started - Python Developer's Guide
You should have been redirected · If not, click here to continue
Lsst
developer.lsst.io › v › DM-7919 › docs › py_docs.html
Documenting Python APIs — LSST DM Developer Guide latest documentation
This format follows the Numpydoc format (used by NumPy, SciPy, and Astropy, among other scientific Python packages) rather than the format described in PEP 287. The sections and their relative order is: ... For functions and methods, the summary should be written in the imperative voice (i.e., ...
Towards Data Science
towardsdatascience.com › home › latest › documenting your python code
Documenting Your Python Code | Towards Data Science
January 27, 2025 - In this article, I will cover the ... to know/practice to be as complete as possible with your documentation. Always add relevant comments to your code where possible. And be mindful of overdoing it by adding comments to everything.
TestDriven.io
testdriven.io › blog › documenting-python
Documenting Python Code and Projects | TestDriven.io
February 9, 2023 - Another type of documentation for developers comes from the tests themselves. As a developer working on a project you need to know more than just how to use a method. You need to know if it works as expected and how to use it to develop further. While adding code examples to docstrings can help with this, such examples are not meant for anything more than simple examples. You need to add tests to cover more than just a function's happy path.
Google
google.github.io › styleguide › pyguide.html
Google Style Guides | Style guides for Google-originated open-source projects
Be sure to use the right style for module, function, method docstrings and inline comments. Python uses docstrings to document code. A docstring is a string that is the first statement in a package, module, class or function. These strings can be extracted automatically through the __doc__ ...