Trong Python, docstrings là một cách để tài liệu hóa các mô-đun, lớp, hàm và phương thức. Chúng được viết trong ba dấu ngoặc kép (""" """) và có thể trải dài qua nhiều dòng.
Docstrings là cách tiện lợi để liên kết tài liệu với mã Python. Chúng có thể được truy cập thông qua thuộc tính __doc__ của các đối tượng Python tương ứng mà chúng tài liệu hóa. Dưới đây là các cách khác nhau để viết docstrings −
Docstring một dòng được sử dụng để cung cấp tài liệu ngắn gọn và đơn giản. Chúng cung cấp một mô tả ngắn gọn về chức năng hoặc phương thức thực hiện. Docstring một dòng nên nằm gọn trong một dòng với ba dấu nháy và kết thúc bằng dấu chấm.
Trong ví dụ sau, chúng ta đang sử dụng một chuỗi tài liệu trên một dòng để viết một đoạn văn bản −
def add(a, b):
"""Return the sum of two numbers."""
return a + b
result = add(5, 3)
print("Sum:", result)
Docstring nhiều dòng được sử dụng để cung cấp tài liệu chi tiết hơn. Chúng cung cấp mô tả toàn diện hơn, bao gồm các tham số, giá trị trả về và các chi tiết liên quan khác. Docstring nhiều dòng bắt đầu và kết thúc bằng ba dấu nháy và bao gồm một dòng tóm tắt theo sau bởi một dòng trống và một mô tả chi tiết hơn.
Ví dụ dưới đây sử dụng chuỗi tài liệu nhiều dòng như một giải thích cho mã −
def multiply(a, b):
"""
Multiply two numbers and return the result.
Parameters:
a (int or float): The first number.
b (int or float): The second number.
Returns:
int or float: The result of multiplying a and b.
"""
return a * b
result = multiply(5, 3)
print("Product:", result)
Khi viết docstring cho các module, hãy đặt docstring ở đầu module, ngay sau bất kỳ câu lệnh import nào. Docstring của module cung cấp cái nhìn tổng quan về chức năng của module và liệt kê các thành phần chính của nó, chẳng hạn như danh sách các hàm, lớp và ngoại lệ được cung cấp bởi module.
Trong ví dụ này, chúng tôi minh họa việc sử dụng docstring cho các module trong Python −
import os
"""
This module provides Utility functions for file handling operations.
Functions:
- 'read_file(filepath)': Reads and returns the contents of the file.
- 'write_file(filepath, content)': Writes content to the specified file.
Classes:
- 'FileNotFoundError': Raised when a file is not found.
Example usage:
>>> import file_utils
>>> content = file_utils.read_file("example.txt")
>>> print(content)
'Hello, world!'
>>> file_utils.write_file("output.txt", "This is a test.")
"""
print("This is os module")
Các lớp có thể có docstring để mô tả mục đích và cách sử dụng của chúng. Mỗi phương thức trong lớp cũng có thể có docstring riêng. Docstring của lớp nên cung cấp cái nhìn tổng quan về lớp và các phương thức của nó.
Trong ví dụ dưới đây, chúng tôi trình bày việc sử dụng docstring cho các lớp trong Python −
class Calculator:
"""
A simple calculator class to perform basic arithmetic operations.
Methods:
- add(a, b): Return the sum of two numbers.
- multiply(a, b): Return the product of two numbers.
"""
def add(self, a, b):
"""Return the sum of two numbers."""
return a + b
def multiply(self, a, b):
"""
Multiply two numbers and return the result.
Parameters:
a (int or float): The first number.
b (int or float): The second number.
Returns:
int or float: The result of multiplying a and b.
"""
return a * b
cal = Calculator()
print(cal.add(87, 98))
print(cal.multiply(87, 98))
Docstrings trong Python được truy cập thông qua thuộc tính __doc__ của đối tượng mà chúng tài liệu hóa. Thuộc tính này chứa chuỗi tài liệu (docstring) liên quan đến đối tượng, cung cấp một cách để truy cập và hiển thị thông tin về mục đích và cách sử dụng của các hàm, lớp, mô-đun hoặc phương thức.
Trong ví dụ sau, chúng ta định nghĩa hai hàm, "add" và "multiply", mỗi hàm có một chuỗi tài liệu mô tả các tham số và giá trị trả về của chúng. Sau đó, chúng ta sử dụng thuộc tính "__doc__" để truy cập và in ra các chuỗi tài liệu này −
# Define a function with a docstring
def add(a, b):
"""
Adds two numbers together.
Parameters:
a (int): The first number.
b (int): The second number.
Returns:
int: The sum of a and b.
"""
return a + b
result = add(5, 3)
print("Sum:", result)
# Define another function with a docstring
def multiply(x, y):
"""
Multiplies two numbers together.
Parameters:
x (int): The first number.
y (int): The second number.
Returns:
int: The product of x and y.
"""
return x * y
result = multiply(4, 7)
print("Product:", result)
# Accessing the docstrings
print(add.__doc__)
print(multiply.__doc__)
Dưới đây là những thực hành tốt nhất để viết docstring trong Python:
Be Clear and Concise − Đảm bảo rằng chuỗi tài liệu giải thích rõ ràng mục đích và cách sử dụng của mã, tránh các chi tiết không cần thiết.
Use Proper Grammar and Spelling − Đảm bảo rằng chuỗi tài liệu được viết tốt với ngữ pháp và chính tả đúng.
Follow Conventions − Sử dụng các quy ước chuẩn để định dạng docstring, chẳng hạn như phong cách Google, phong cách NumPy hoặc phong cách Sphinx.
Include Examples − Cung cấp ví dụ khi có thể để minh họa cách sử dụng mã đã được tài liệu hóa.
Docstring theo kiểu Google cung cấp một cách có cấu trúc để tài liệu hóa mã Python bằng cách sử dụng thụt lề và tiêu đề. Chúng được thiết kế để dễ đọc và cung cấp thông tin, tuân theo một định dạng cụ thể.
Dưới đây là một ví dụ về một hàm với docstring theo phong cách Google −
def divide(dividend, divisor):
"""
Divide two numbers and return the result.
Args:
dividend (float): The number to be divided.
divisor (float): The number to divide by.
Returns:
float: The result of the division.
Raises:
ValueError: If `divisor` is zero.
"""
if divisor == 0:
raise ValueError("Cannot divide by zero")
return dividend / divisor
result = divide(4, 7)
print("Division:", result)
Docstring theo phong cách NumPy/SciPy rất phổ biến trong tính toán khoa học. Chúng bao gồm các phần cho tham số, giá trị trả về và ví dụ.
Dưới đây là một ví dụ về một hàm với docstring theo phong cách NumPy/SciPy −
def fibonacci(n):
"""
Compute the nth Fibonacci number.
Parameters
----------
n : int
The index of the Fibonacci number to compute.
Returns
-------
int
The nth Fibonacci number.
Examples
--------
>>> fibonacci(0)
0
>>> fibonacci(5)
5
>>> fibonacci(10)
55
"""
if n == 0:
return 0
elif n == 1:
return 1
else:
return fibonacci(n-1) + fibonacci(n-2)
result = fibonacci(4)
print("Result:", result)
Docstring theo kiểu Sphinx tương thích với trình tạo tài liệu Sphinx và sử dụng định dạng reStructuredText .
reStructuredText (reST) là một ngôn ngữ đánh dấu nhẹ được sử dụng để tạo ra các tài liệu văn bản có cấu trúc. Trình tạo tài liệu Sphinx nhận các tệp "reStructuredText" làm đầu vào và tạo ra tài liệu chất lượng cao ở nhiều định dạng khác nhau, bao gồm HTML, PDF, ePub và nhiều hơn nữa.
Dưới đây là một ví dụ về một hàm với chuỗi tài liệu theo kiểu Sphinx −
def divide(dividend, divisor):
"""
Divide two numbers and return the result.
Args:
dividend (float): The number to be divided.
divisor (float): The number to divide by.
Returns:
float: The result of the division.
Raises:
ValueError: If `divisor` is zero.
"""
if divisor == 0:
raise ValueError("Cannot divide by zero")
return dividend / divisor
result = divide(76, 37)
print("Result:", result)
Dưới đây là những điểm khác biệt được nêu bật giữa docstring trong Python và chú thích, tập trung vào mục đích, định dạng, cách sử dụng và khả năng truy cập của chúng:
| Docstring | Comment |
|---|---|
| Used to document Python objects such as functions, classes, methods, modules, or packages. | Used to annotate code for human readers, provide context, or temporarily disable code. |
| Written within triple quotes (""" """ or ''' ''') and placed immediately after the object's definition. | Start with the # symbol and are placed on the same line as the annotated code. |
| Stored as an attribute of the object and accessible programmatically. | Ignored by the Python interpreter during execution, purely for human understanding. |
| Accessed using the __doc__ attribute of the object. | Not accessible programmatically; exists only in the source code. |