Sitemap
The Simple Learning

The Simple Learning

Big Data, Data Engineering, Data Modeling

Document Your Code

2 min readMar 11, 2024
Press enter or click to view image in full size

It’s like putting labels on different parts of a Lego set so you remember how to build it later. It helps other people understand your code better, like reading a storybook with pictures and words. Just like following a recipe when baking cookies, documenting your code makes it easier to share and understand how everything works together.

Best Practices for Code Documentation:

  1. Use Descriptive Variable and Function Names:
  • Choose meaningful and descriptive names for variables, functions, and classes to convey their purpose and functionality.

2. Write Clear Comments:

  • Include comments throughout the code to explain complex logic, algorithms, or any non-obvious functionality.
  • Use comments to document the intent behind specific code blocks or sections.

3. Document Function Signatures:

  • Provide clear documentation for function signatures, including parameters, return types, and any exceptions raised.
  • Use docstrings to document functions, classes, and modules in Python.

4. Include Examples and Usage Patterns:

  • Provide usage examples and usage patterns in docstrings to illustrate how to use the function or class effectively.

5. Update Documentation Regularly:

  • Keep the documentation up-to-date with any changes or enhancements made to the codebase.
  • Review and update documentation during code reviews and refactorings.

For Python PEP 257 is defined Docstring Conventions. Which Suggest:

  1. One-Line Docstrings:
  • For simple functions or methods, a one-line docstring should be used. It should be enclosed in triple quotes (""") and placed immediately after the function or method definition.
def my_function(arg):
"""One-line docstring."""
# Function body

2. Multi-Line Docstrings:

  • For more complex functions or methods, multi-line docstrings are recommended. They should consist of a one-line summary followed by a blank line and a more detailed description.
def my_function(arg):
"""
Summary line.

Detailed description of the function.
More details can be provided here.
"""
# Function body

3. Docstring Content:

  • Docstrings should describe what the function or method does, including its purpose, arguments (if any), return values (if any), and any exceptions raised.
  • It should provide enough information for users to understand how to use the function or method correctly.

4. Quotes Style:

  • Docstrings should use triple quotes (""") for consistency and to support multi-line strings.

5. Whitespace:

  • Use a blank line before and after the docstring to separate it from the rest of the code for clarity.

6. Docstring Location:

  • Docstrings should be placed immediately after the function, method, class, or module definition.

7. Punctuation:

  • Use proper punctuation and grammar in docstrings to ensure clarity and readability.

By following these best practices and understanding the benefits of code documentation, developers can contribute to building maintainable, robust, and collaborative codebases in Python.

Get The Simple Learning’s stories in your inbox

Join Medium for free to get updates from this writer.

Do like, comment, follow and share.

--

--

The Simple Learning
The Simple Learning

Written by The Simple Learning

Big Data, Data Engineering, Data Modeling