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

Code tốt bao gồm bình luận để hiểu rõ về nó. Docstrings có thể giúp bạn làm việc này dễ dàng.

Nếu không có tài liệu phù hợp, thật khó hiểu, duy trì và gỡ lỗi code. Trong Python, bạn có thể dùng docstring để cung cấp mô tả chính xác cùng ví dụ về cách code hoạt động.

Docstrings là gì?

Docstrings là một chuỗi mà bạn có thể thêm vào code Python để giải thích ý nghĩa và cách dùng nó. Phần code này có thể là một hàm Python, một mô đun hoặc class.

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

Mặt khác, docstrings chủ yếu cung cấp thông tin cho người dùng code mà chưa nhất thiết cần biết chi tiết triển khai của nó nhưng cần hiểu tác dụng và cách dùng nó.

Cách viết Docstrings

Docstring thường được bao gồm ở phần đầu code mà bạn muốn ghi lại. Bạn phải đặt chúng trong dấu ngoặc kép. Bạn có thể viết docstring 1 dòng hoặc nhiều dòng.

Docstrings 1 dòng phù hợp với code đơn giản mà không cần nhiều dữ kiện.

Bên dưới là một ví dụ của hàm multiply. Docstring giải thích hàm multiply tính 2 số, nhân chúng và trả về kết quả.

def multiply(a, b):
    """Nhân 2 số và trả về kết quả"""
    return a * b

Dùng docstring đa dòng cho code phức tạp hơn, cần dữ liệu chi tiết.

Cân nhắc dùng class Car sau:

class Car:
    """
    Class đại diện cho đối tượng xe hơi.

    Attributes:
        mileage (float): Số dặm xe hiện tại xe đã đi được.

    Methods:
        drive(miles): Lái xe theo số dặm cụ thể.
    """

    def __init__(self, mileage):
        self.mileage = mileage

    def drive(self, miles):
        """
        Lái xe theo số dặm cụ thể.

        Args:
            miles (float): Số dặm cần lái.

        Returns:
            None
        """
              self.mileage += miles

Docstring cho class ở trên mô tả thông tin class đại diện, thuộc tính và phương thức của nó. Trong khi đó, docstrings cho phương thức drive cung cấp thông tin về nhiệm vụ, đối số và kết quả nó trả về.

Điều này khiến bất kỳ ai làm việc với class trên đều hiểu cách dùng nó. Lợi ích khác của việc dùng docstrings bao gồm:

• Duy trì code: Bằng cách cung cấp mô tả rõ ràng về cách code hoạt động, docstrings giúp lập trình viên chỉnh sửa và update code mà không cần giới thiệu lỗi.
• Dễ dàng hợp tác hơn: Khi một số lập trình viên hợp tác trên cùng code base - ví dụ, với công cụ chia sẻ trực tiếp Visual Studio - docstrings cho phép lập trình viên ghi lại code nhất quán để mọi người trong đội có thể hiểu nó.
• Cải thiện khả năng đọc code: Docstrings cung cấp tóm tắt cấp độ cao về cách code cho phép mọi người đọc nó để hiểu nhanh mục đích mà không cần đọc hết toàn bộ khối code.

Định dạng Docstring

Một docstring tốt cần mô tả một phần nội dung của code, các đối số nó mong đợi và chi tiết triển khai nếu cần. Đặc biệt, nó sẽ tự động bao gồm những trường hợp đặc biệt mà bất kỳ ai dùng code đều nên biết.

Định dạng docstring cơ bản có các phần sau:

• Dòng tóm tắt: Tóm tắt 1 dòng về ý nghĩa của code.
• Đối số: Thông tin về các đối số hàm mong đợi bao gồm 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 kiểu dữ liệu của nó.
• Phát sinh (Tùy chọn): Thông tin về bất kỳ trường hợp ngoại lệ có thể phát sinh.

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

Epytext

Một docstring theo định dang 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

reStructuredText (reST)

Một docstring 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 docstring 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 docstring 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ù tất cả 4 định dạng docstring đều cung cấp dữ liệu hữu ích cho hàm multiply, định dạng NumPy và Google vẫn dễ đọc hơn Epytext và reST.

Cách bao gồm test trong Docstring

Bạn có thể bao gồm các ví dụ thử nghiệm trong docstrings bằng mô đun doctest. Mô đun này tìm docstring cho text trông giống như các phiên Python tương tác, rồi chạy chúng để xác minh rằng chúng hoạt động bình thường.

Để dùng doctest, bao gồm các input mẫu và output dự kiến trong docstring. Bên dưới là ví dụ về cách bạn có thể làm việc này:

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

Phần Examples chứa 3 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 chạy mô đun doctest như hình bên dưới, nó sẽ chạy các mẫu và so sánh kết quả thực sự với kết quả được mong đợi.

python -m doctest multiply.py

Nếu có bất kỳ sự khác biệt, mô đun doctest báo cáo chúng bị lỗi hay chạy thất bại. Dùng doctest với docstring giúp bạn xác minh code có đang hoạt động như mong đợi.

Trên đây là những điều bạn cần biết về cách ghi code Python bằng docstring. Hi vọng bài viết hữu ích với các bạn.