Python - Docstrings

Xin chào, các nhà lập trình Python đam mê! Hôm nay, chúng ta sẽ bơi lội vào thế giới kỳ diệu của docstrings. Là một giáo viên khoa học máy tính bạn thân thiện, tôi rất vui mừng hướng dẫn bạn qua khía cạnh quan trọng này của lập trình Python. Vậy hãy lấy ly đồ uống yêu thích của bạn, thoải mái đi, và hãy cùng nhau bắt đầu chuyến phiêu lưu học hỏi này!

Docstrings trong Python

Tưởng tượng bạn đang viết một cuộn nhật ký. Ở đầu mỗi bài ghi, bạn có thể ghi chú một câu tóm tắt ngắn gọn về những gì đã xảy ra trong ngày hôm đó. Thật tuyệt vời, docstrings trong Python cũng có phần tương tự! Chúng là các chuỗi đặc biệt mô tả những gì một đoạn mã làm, giúp bạn (và những người khác) dễ dàng hiểu mã của mình sau này.

Trong Python, docstrings được bao bọc bởi ba dấu nháy kép (""" hoặc ''') và được đặt ngay sau định nghĩa của hàm, lớp hoặc mô-đun. Hãy xem một ví dụ đơn giản:

def greet(name):
"""Hàm này chào đón người được truyền vào dưới dạng tham số"""
print(f"Xin chào, {name}!")

Trong ví dụ này, dòng giữa ba dấu nháy kép là docstring của chúng ta. Nó mô tả ngắn gọn những gì hàm greet làm.

Docstrings một dòng

Đối với các hàm hoặc lớp đơn giản, một docstring một dòng có thể là tất cả bạn cần. Dưới đây là một ví dụ khác:

def square(n):
"""Trả về bình phương của một số."""
return n ** 2

Docstring này ngắn gọn và đẹp, nó nói rõ ràng chính xác những gì hàm này làm chỉ trong một dòng.

Docstrings nhiều dòng

Đối với các hàm hoặc lớp phức tạp hơn, bạn có thể cần một docstring nhiều dòng. Các docstring này thường bao gồm một dòng tóm tắt, sau đó là một dòng trống, và sau đó là thông tin chi tiết hơn. Hãy xem một ví dụ:

def calculate_area(length, width):
"""
Tính diện tích của một hình chữ nhật.

Tham số:
length (float): Độ dài của hình chữ nhật
width (float): Độ rộng của hình chữ nhật

Trả về:
float: Diện tích của hình chữ nhật
"""
return length * width

Docstring nhiều dòng này cung cấp thông tin chi tiết hơn về các tham số của hàm và những gì nó trả về.

Docstrings cho các mô-đun

Các mô-đun cũng có thể có docstrings! Chúng được đặt ở đầu tiên của tệp. Ví dụ:

"""
Mô-đun này chứa các hàm tiện ích cho các phép toán hình học.
Nó bao gồm các hàm để tính diện tích và thể tích của các hình đa dạng.
"""

def calculate_circle_area(radius):
# Công thức thực hiện ở đây

Docstrings cho các lớp

Các lớp cũng có thể có docstrings. Chúng được đặt ngay sau định nghĩa lớp:

class Rectangle:
"""
Một lớp đại diện cho hình chữ nhật.

Thuộc tính:
length (float): Độ dài của hình chữ nhật
width (float): Độ rộng của hình chữ nhật
"""

def __init__(self, length, width):
self.length = length
self.width = width

Truy cập Docstrings

Một điều thú vị về docstrings là bạn có thể truy cập chúng một cách lập trình. Python lưu trữ docstring dưới dạng thuộc tính __doc__ của hàm, lớp hoặc mô-đun. Dưới đây là cách bạn có thể truy cập nó:

def greet(name):
"""Hàm này chào đón người được truyền vào dưới dạng tham số"""
print(f"Xin chào, {name}!")

print(greet.__doc__)

Điều này sẽ xuất ra: Hàm này chào đón người được truyền vào dưới dạng tham số

Các quy tắc tốt nhất khi viết Docstrings

Bây giờ khi chúng ta biết cách viết docstrings, hãy nói về một số quy tắc tốt nhất:

1. Có một ngắn gọn nhưng cần thiết
2. Sử dụng ngữ pháp và dấu câu đúng
3. Đặt đúng kiểu cách
4. Bao gồm thông tin về các tham số và giá trị trả về của hàm
5. Đối với các lớp, mô tả các thuộc tính và phương thức quan trọng

Kiểu Docstring theo phong cách Google

Google có tài liệu riêng cho docstrings. Dưới đây là một ví dụ:

def divide(a, b):
"""Chia hai số.

Args:
a (int): Tử số.
b (int): Mẫu số.

Returns:
float: Kết quả của phép chia.

Raises:
ZeroDivisionError: Nếu b là 0.
"""
if b == 0:
raise ZeroDivisionError("Không thể chia cho không")
return a / b

Kiểu Docstring theo phong cách NumPy/SciPy

Nếu bạn làm việc với các thư viện khoa học Python, bạn có thể gặp kiểu NumPy/SciPy:

def calculate_mean(numbers):
"""
Tính trung bình Arithmetic của một danh sách các số.

Parameters
----------
numbers : list
Danh sách các số.

Returns
-------
float
Trung bình Arithmetic của danh sách đầu vào.
"""
return sum(numbers) / len(numbers)

Kiểu Docstring theo phong cách Sphinx

Sphinx là một trình tạo tài liệu phổ biến cho Python. Phong cách của nó tương tự như định dạng reStructuredText:

def fibonacci(n):
"""
Tạo một chuỗi Fibonacci đến n.

:param n: Số các số Fibonacci để tạo ra
:type n: int
:return: Danh sách các số Fibonacci
:rtype: list
"""
sequence = [0, 1]
while len(sequence) < n:
sequence.append(sequence[-1] + sequence[-2])
return sequence[:n]

So sánh Docstring và Comment

Bạn có thể hỏi, "Chênh lệch giữa docstring và comment thường là gì?" Đây là một câu hỏi tuyệt vời! Hãy phân tích nó:

1. Cú pháp: Docstrings sử dụng ba dấu nháy kép, trong khi comment sử dụng #.
2. Vị trí: Docstrings đặt ngay sau định nghĩa, trong khi comment có thể đặt bất kỳ đâu.
3. Mục đích: Docstrings mô tả những gì mã làm, trong khi comment mô tả cách nó làm.
4. Truy cập: Docstrings có thể truy cập một cách lập trình, trong khi comment không thể.

Dưới đây là một ví dụ nhanh để minh họa:

def add(a, b):
"""
Cộng hai số và trả về kết quả.
"""
# Đây là comment giải thích cách chúng ta thực hiện phép cộng
return a + b  # Đây là comment inline

Và đó là tất cả, các bạn! Chúng ta đã bào trùm khái niệm về Python docstrings. Hãy nhớ, tài liệu tốt như để lại một vết sẹo dẫn cho tương lai bạn (hoặc các nhà phát triển khác) để theo dõi. Nó có thể có vẻ như là công việc thêm vào bây giờ, nhưng tin tôi, bạn sẽ cảm ơn mình sau này!

Dưới đây là bảng tóm tắt nhanh về các kiểu docstring mà chúng ta đã nói về:

Phong cách	Tóm tắt	Ví dụ
Một dòng	Mô tả ngắn gọn một dòng	"""Trả về bình phương của một số."""
Nhiều dòng	Mô tả chi tiết với các tham số và giá trị trả về	"""Tính diện tích của một hình chữ nhật.\n\nTham số:\n..."""
Google	Bao gồm các phần Args, Returns và Raises	"""Chia hai số.\n\nArgs:\n..."""
NumPy/SciPy	Sử dụng các phần Parameters và Returns với định dạng chi tiết hơn	"""Tính trung bình Arithmetic của một danh sách các số.\n\nParameters\n----------\n..."""
Sphinx	Sử dụng các trường :param:, :type:, :return:, và :rtype:	"""Tạo một chuỗi Fibonacci đến n.\n\n:param n: ..."""

Chúc các bạn mãi mãi mã code mạnh mẽ, và docstrings của các bạn luôn rõ ràng và có ý nghĩa!

Credits: Image by storyset