Cách ghi lại mã Python bằng Docstrings

Nếu không có tài liệu thích hợp, có thể khó hiểu, bảo trì và gỡ lỗi mã của bạn. Trong Python, bạn có thể sử dụng chuỗi tài liệu để cung cấp các mô tả và ví dụ ngắn gọn về cách hoạt động của mã.

Tài liệu là gì?

Docstrings là các chuỗi bạn có thể thêm vào mã Python của mình để giải thích chức năng của nó và cách sử dụng nó. Đoạn mã có thể là một hàm Python, một mô-đun hoặc một lớp.

Các chuỗi tài liệu trông rất giống với các nhận xét tiêu chuẩn của Python, nhưng chúng có một số khác biệt. Nhận xét Python cung cấp thông tin bổ sung cho nhà phát triển về hoạt động bên trong của mã, chẳng hạn như chi tiết triển khai hoặc lưu ý cần lưu ý khi mở rộng mã.

Mặt khác, các chuỗi tài liệu chủ yếu cung cấp thông tin cho người dùng mã, những người có thể không nhất thiết phải biết chi tiết triển khai của nó nhưng cần hiểu những gì nó làm và cách sử dụng nó.

Làm thế nào để Viết Docstrings

Bạn thường bao gồm các chuỗi tài liệu ở đầu khối mã mà bạn muốn ghi lại. Bạn phải đặt chúng trong ba dấu ngoặc kép (“””). Bạn có thể viết chuỗi tài liệu một dòng hoặc chuỗi tài liệu nhiều dòng.

Chuỗi tài liệu một dòng phù hợp với mã đơn giản không yêu cầu nhiều tài liệu.

Dưới đây là một ví dụ về một chức năng được gọi là nhân lên. Chuỗi tài liệu giải thích hàm nhân lấy hai số, nhân chúng và trả về kết quả.

 def multiply(a, b):
    """Multiplies two numbers and returns the result"""
    return a * b
 

Sử dụng chuỗi tài liệu nhiều dòng cho mã phức tạp hơn cần tài liệu chi tiết.

Xét lớp Car sau:

 class Car:
    """
    A class representing a car object.
    Attributes:
        mileage (float): The current mileage of the car.
    Methods:
        drive(miles): Drives the car for the specified number of miles.
    """
    def __init__(self, mileage):
        self.mileage = mileage
    def drive(self, miles):
        """
        Drives the car for the specified number of miles.
        Args:
            miles (float): The number of miles to drive.
        Returns:
            None
        """
        self.mileage += miles
 

Chuỗi tài liệu cho lớp trên mô tả những gì lớp đại diện, các thuộc tính và phương thức của nó. Trong khi đó, các chuỗi tài liệu cho phương thức ổ đĩa cung cấp thông tin về những gì phương thức thực hiện, các đối số mà nó mong đợi và những gì nó trả về.

Điều này giúp bất kỳ ai làm việc với lớp này hiểu cách sử dụng nó dễ dàng hơn. Các lợi ích khác của việc sử dụng docstrings bao gồm:

• Khả năng bảo trì mã: Bằng cách cung cấp mô tả rõ ràng về cách hoạt động của mã, chuỗi tài liệu giúp nhà phát triển sửa đổi và cập nhật mã mà không gây ra lỗi.
• Cộng tác dễ dàng hơn: Khi một số nhà phát triển cộng tác trên cùng một cơ sở mã—ví dụ: với công cụ chia sẻ trực tiếp Visual Studio—các chuỗi tài liệu cho phép nhà phát triển ghi lại mã một cách nhất quán để mọi người trong nhóm có thể hiểu mã.
• Khả năng đọc mã được cải thiện: Tài liệu cung cấp bản tóm tắt cấp cao về chức năng của mã, cho phép bất kỳ ai đọc mã hiểu nhanh mục đích của mã mà không cần xem qua toàn bộ khối mã.

Định dạng chuỗi tài liệu

Một chuỗi tài liệu tốt nên mô tả chức năng của một đoạn mã, các đối số mà nó mong đợi và chi tiết triển khai nếu cần. Nó đặc biệt nên bao gồm bất kỳ trường hợp cạnh nào mà bất kỳ ai sử dụng mã nên biết.

Một định dạng chuỗi tài liệu cơ bản có các phần sau:

• Dòng tóm tắt: Tóm tắt một dòng về chức năng của mã.
• Đối số: Thông tin về các đối số mà hàm mong đợi bao gồm cả kiểu dữ liệu của chúng.
• Giá trị trả về: Thông tin về giá trị trả về của hàm bao gồm cả kiểu dữ liệu của nó.
• Tăng (tùy chọn): Thông tin về bất kỳ trường hợp ngoại lệ nào mà chức năng có thể tăng.

Đây chỉ là định dạng cơ bản vì có các định dạng khác mà bạn có thể chọn để làm cơ sở cho chuỗi tài liệu của mình. Những cái phổ biến nhất là Epytext, reStructuredText (còn được gọi là reST), NumPy và Google docstrings. Mỗi định dạng này có cú pháp riêng như minh họa trong các ví dụ sau:

văn bản

Một chuỗi tài liệu tuân theo định dạng Epytext:

 def multiply(a, b):
    """
    Multiply two numbers together.
 @param a: The first number to multiply.
 @type a: int
 @param b: The second number to multiply.
 @type b: int
 @return: The product of the two numbers.
 @rtype: int
    """
    return a * b
 

tái cấu trúc văn bản (reST)

Một chuỗi tài liệu tuân theo định dạng reST:

 def multiply(a, b):
    """
    Multiply two numbers together.
    :param a: The first number to multiply.
    :type a: int
    :param b: The second number to multiply.
    :type b: int
    :return: The product of the two numbers.
    :rtype: int
    """
    return a * b
 

NumPy

Một chuỗi tài liệu tuân theo định dạng NumPy:

 def multiply(a, b):
    """
    Multiply two numbers together.
    Parameters
    ----------
    a : int
        The first number to multiply.
    b : int
        The second number to multiply.
    Returns
    -------
    int
        The product of the two numbers.
    """
    return a * b
 

Google

Một chuỗi tài liệu tuân theo định dạng Google:

 def multiply(a, b):
    """
    Multiply two numbers together.
    Args:
        a (int): The first number to multiply.
        b (int): The second number to multiply.
    Returns:
        int: The product of the two numbers.
    """
    return a * b
 

Mặc dù cả bốn định dạng chuỗi tài liệu đều cung cấp tài liệu hữu ích cho hàm nhân, định dạng NumPy và Google dễ đọc hơn định dạng Epytext và reST.

Cách đưa các bài kiểm tra vào Tài liệu

Bạn có thể bao gồm các ví dụ thử nghiệm trong chuỗi tài liệu của mình bằng cách sử dụng mô-đun doctest. Mô-đun doctest tìm kiếm chuỗi tài liệu để tìm văn bản trông giống như các phiên Python tương tác, sau đó thực thi chúng để xác minh rằng chúng hoạt động bình thường.

Để sử dụng tài liệu, hãy bao gồm đầu vào mẫu và đầu ra dự kiến ​​trong chuỗi tài liệu. Dưới đây là một ví dụ về cách bạn sẽ làm điều đó:

 def multiply(a, b):
    """
    Multiply two numbers together.
    Parameters
    ----------
    a : int
        The first number to multiply.
    b : int
        The second number to multiply.
    Returns
    -------
    int
        The product of the two numbers.
    Examples
    --------
    >>> multiply(2, 3)
    6
    >>> multiply(0, 10)
    0
    >>> multiply(-1, 5)
    -5
    """
    return a * b
 

Các ví dụ chứa ba lệnh gọi hàm với các đối số khác nhau và chỉ định đầu ra dự kiến ​​cho mỗi lệnh. Khi bạn chạy mô-đun doctest như hình bên dưới, nó sẽ thực thi các ví dụ và so sánh đầu ra thực tế với đầu ra dự kiến.

 python -m doctest multiply.py
 

Nếu có bất kỳ sự khác biệt nào, mô-đun doctest sẽ báo cáo chúng là lỗi. Sử dụng tài liệu có chuỗi tài liệu như thế này giúp bạn xác minh rằng mã đang hoạt động như mong đợi. Lưu ý rằng doctests không phải là sự thay thế cho các bài kiểm tra đơn vị và kiểm tra tích hợp toàn diện hơn cho mã Python của bạn.

Cách tạo tài liệu từ Docstrings

Bạn đã học những kiến ​​thức cơ bản về cách sử dụng chuỗi tài liệu để ghi lại mã Python của mình và tầm quan trọng của tài liệu chất lượng cao. Để nâng cao nó, bạn có thể muốn tạo tài liệu cho các mô-đun và chức năng của mình từ các chuỗi tài liệu tương ứng của chúng.

Một trong những trình tạo tài liệu phổ biến nhất mà bạn có thể sử dụng là Sphinx. Nó hỗ trợ định dạng chuỗi tài liệu reST theo mặc định nhưng bạn có thể định cấu hình để nó hoạt động với định dạng Google hoặc NumPy.