To write a good Python document, the key is to have clear structure, prominent focus, and comply with tool analysis standards. First, docstring should be used instead of ordinary annotations to be recognized by Sphinx or help() tools; second, it is recommended to use standard formats such as Google style to improve readability and compatibility; then each class and method should contain function descriptions, parameters, return values ??and exception descriptions; in addition, it is recommended to add usage examples to help understand, and add precautions or warning messages to remind potential problems.
When writing good Python documentation, the key is to let others (or you in the future) quickly understand what this class is for and how to use it. It is not just a few comments to add a few comments to the document, the structure must be clear and the key points must be prominent, and it is best to meet the standards of tool analysis.
Use docstring instead of comments
Python classes and methods should use docstring to write documents, rather than ordinary comments. Because docstring can be recognized by document generation tools like Sphinx, it can also be viewed directly through help() or .__doc__ in an interactive environment.
For example:
class MyList:
"""A simplified version of the list container, supporting basic addition and deletion operations.
Attributes:
data (list): internally stored data list """
def __init__(self):
"""Initialize an empty list"""
self.data = [] After writing this way, enter help(MyList) in IPython or Jupyter and you will see the instructions you wrote.
Follow common format specifications
Although you are free to write docstring, for uniformity and readability, it is recommended to use a standard format such as reST (Sphinx), Google style or NumPy style.
Recommended Google style, simple and easy to read:
class Calculator:
"""Class for performing basic mathematical operations.
Args:
precision (int): The accuracy when calculating floating point numbers, default to 2-digit decimal Attributes:
precision (int): The current set accuracy value """If you are using VSCode or PyCharm, many IDE plug-ins can automatically generate templates in this format, just fill in the content.
Write common methods and usages into
In addition to the overall description of the class, each method exposed to the outside should also have docstring, especially parameters, return values ??and possible exceptions.
for example:
def add(self, a, b):
"""Add two numbers and round Args according to the current precision:
a (float): the first adder b (float): the second adder Returns:
float: Addition result, rounded """
result = round(ab, self.precision)
return resultThis part is especially important if you provide a library for others. Users don't need to see how you implement it, but they need to know how to call, what parameters are passed, and what will be returned.
Don't ignore examples and notes
Sometimes adding one or two simple usage examples is more effective than writing ten descriptions. for example:
class Stack:
"""A simple stack implementation Example:
>>> s = Stack()
>>> s.push(1)
>>> s.push(2)
>>> s.pop()
2
""" In addition, if some methods have side effects, thread insecure, dependence on external states, etc., you can also add Note: or Warning: to remind users.
Basically that's it. Writing a class document is not difficult, the key is to develop a habit, and make up a few sentences to explain each time you write the class and method. It seems like a small thing, but it helps a lot in the long run for maintenance and collaboration.
The above is the detailed content of How to document a python class. For more information, please follow other related articles on the PHP Chinese website!
Hot AI Tools
Undress AI Tool
Undress images for free
Undresser.AI Undress
AI-powered app for creating realistic nude photos
AI Clothes Remover
Online AI tool for removing clothes from photos.
Clothoff.io
AI clothes remover
Video Face Swap
Swap faces in any video effortlessly with our completely free AI face swap tool!
Hot Article
Hot Tools
Notepad++7.3.1
Easy-to-use and free code editor
SublimeText3 Chinese version
Chinese version, very easy to use
Zend Studio 13.0.1
Powerful PHP integrated development environment
Dreamweaver CS6
Visual web development tools
SublimeText3 Mac version
God-level code editing software (SublimeText3)
Insufficient memory or disk space to repagin or print this document Word error
Feb 19, 2024 pm 07:15 PM
This article will introduce how to solve the problem of insufficient memory or disk space to repage or print the document in Microsoft Word. This error usually occurs when users try to print a Word document. If you encounter a similar error, please refer to the suggestions provided in this article to resolve it. Insufficient memory or disk space to repage or print this document Word error How to resolve the Microsoft Word printing error "There is not enough memory or disk space to repage or print the document." Update Microsoft Office Close memory-hogging applications Change your default printer Start Word in safe mode Rename the NorMal.dotm file Save the Word file as another
How to add redline to Word document
Mar 01, 2024 am 09:40 AM
It is 395 words, which is 495. This article will show you how to add red lines in Word documents. Redlining a document refers to making modifications to the document so that users can clearly see the changes. This feature is very important when multiple people are editing a document together. What redline means Marking a document Redlining means using red lines or callouts to indicate changes, edits, or revisions to a document. The term was inspired by the practice of using a red pen to mark printed documents. Redline comments are widely used in different scenarios, such as clearly showing recommended changes to authors, editors, and reviewers when editing a document. Propose changes and modifications in legal agreements or contracts Provide constructive criticism and suggestions on papers, presentations, etc. How to give W
Can't open hyperlink in word document
Feb 18, 2024 pm 06:10 PM
In recent years, with the continuous development of network technology, our lives are inseparable from various digital tools and the Internet. When processing documents, especially in writing, we often use word documents. However, sometimes we may encounter a difficult problem, that is, the hyperlink in the word document cannot be opened. This issue will be discussed below. First of all, we need to make it clear that hyperlinks refer to links added in word documents to other documents, web pages, directories, bookmarks, etc. When we click on these links, I
Learn the os.Stdout.Write function in the Go language documentation to implement standard output
Nov 03, 2023 pm 03:48 PM
Learn the os.Stdout.Write function in the Go language documentation to implement standard output. In the Go language, standard output is implemented through os.Stdout. os.Stdout is a variable of type *os.File, which represents the standard output device. In order to output content to standard output, you can use the os.Stdout.Write function. This article will introduce how to use the os.Stdout.Write function to implement standard output and provide specific code examples. os.
Word document is blank when opening on Windows 11/10
Mar 11, 2024 am 09:34 AM
When you encounter a blank page issue when opening a Word document on a Windows 11/10 computer, you may need to perform repairs to resolve the situation. There are various sources of this problem, one of the most common being a corrupted document itself. Furthermore, corruption of Office files may also lead to similar situations. Therefore, the fixes provided in this article may be helpful to you. You can try to use some tools to repair the damaged Word document, or try to convert the document to another format and reopen it. In addition, checking whether the Office software in the system needs to be updated is also a way to solve this problem. By following these simple steps, you may be able to fix Word document blank when opening Word document on Win
Detailed explanation of Word document operation: merge two pages into one
Mar 26, 2024 am 08:18 AM
Word documents are one of the most frequently used applications in our daily work and study. When working with documents, you may sometimes encounter a situation where you need to merge two pages into one. This article will introduce in detail how to merge two pages into one page in a Word document to help readers handle document layout more efficiently. In Word documents, the operation of merging two pages into one is usually used to save paper and printing costs, or to make the document more compact and neat. The following are the specific steps to merge two pages into one: Step 1: Open the Word that needs to be operated
How to implement the basic usage of Workerman documents
Nov 08, 2023 am 11:46 AM
Introduction to how to implement the basic usage of Workerman documents: Workerman is a high-performance PHP development framework that can help developers easily build high-concurrency network applications. This article will introduce the basic usage of Workerman, including installation and configuration, creating services and listening ports, handling client requests, etc. And give corresponding code examples. 1. Install and configure Workerman. Enter the following command on the command line to install Workerman: c
Interpretation of Java documentation: Detailed introduction to the substring() method of the StringBuilder class
Nov 03, 2023 pm 04:31 PM
Interpretation of Java documentation: Detailed introduction to the substring() method of the StringBuilder class Introduction: In Java programming, string processing is one of the most common operations. Java provides a series of classes and methods for string processing, among which the StringBuilder class is a commonly used choice for frequent string operations. In the StringBuilder class, the substring() method is a very useful method for intercepting substrings of strings. This article will
