Trả về chuỗi tài liệu Python

Ghi lại mã của bạn là một kỹ năng quan trọng đối với bất kỳ nhà khoa học dữ liệu hoặc kỹ sư phần mềm nào. Tìm hiểu làm thế nào để làm điều đó bằng cách sử dụng docstrings

Tại sao tài liệu trong Python lại quan trọng?

Điều này cho chúng ta biết rằng "Khả năng đọc được tính" và "Rõ ràng tốt hơn ẩn. " Đây là những đặc điểm cần thiết của Python. Khi chúng tôi viết mã, chúng tôi làm điều đó cho người dùng cuối, nhà phát triển và chính chúng tôi

Hãy nhớ rằng chúng ta cũng là người dùng cuối khi đọc tài liệu

    3

6 hoặc tài liệu

    3

7. Hai gói này có tài liệu tuyệt vời và người dùng thường không gặp khó khăn gì khi sử dụng chúng vì chúng chứa rất nhiều ví dụ và hướng dẫn. Họ cũng có tài liệu tích hợp mà chúng tôi có thể truy cập trực tiếp vào IDE ưa thích của bạn

Bây giờ hãy tưởng tượng sử dụng các gói này mà không có bất kỳ tài liệu tham khảo nào. Chúng tôi sẽ cần tìm hiểu mã của họ để hiểu nó làm gì và cách chúng tôi có thể sử dụng nó. Có một số gói hoàn toàn không có tài liệu hướng dẫn và thường mất nhiều thời gian hơn để hiểu những gì bên trong chúng và cách chúng ta có thể sử dụng chúng. Khối lượng công việc này tăng gấp đôi hoặc gấp ba nếu gói lớn, với các chức năng trải rộng trên nhiều tệp

Bây giờ rõ ràng hơn tại sao tài liệu tốt lại được tính

Tiếp theo, các nhà phát triển khác có thể muốn đóng góp cho các dự án của chúng tôi. Họ có thể làm điều đó nhanh hơn và hiệu quả hơn nhiều nếu mã của chúng tôi được ghi chép đầy đủ. Bạn có muốn đóng góp cho một dự án trong thời gian rảnh nếu bạn phải dành hàng giờ để tìm hiểu những phần khác nhau của nó làm gì không?

Cuối cùng, ngay cả khi đó chỉ là dự án riêng của chúng tôi hoặc một tập lệnh nhỏ, chúng tôi vẫn cần tài liệu. Chúng tôi không bao giờ biết khi nào chúng tôi sẽ quay lại một trong những dự án cũ của mình để sửa đổi hoặc cải thiện nó. Thật thú vị và dễ làm việc với nó nếu nó cho chúng ta biết rõ ràng nó dùng để làm gì và các chức năng, dòng mã và mô-đun của nó làm gì. Chúng ta có xu hướng nhanh chóng quên đi những gì mình đang nghĩ trong quá trình viết mã, vì vậy, dành thời gian giải thích lý do tại sao chúng ta đang làm điều gì đó luôn tiết kiệm nhiều thời gian hơn khi quay lại mã [ngay cả khi nó mới được viết một ngày trước]. Vì vậy, hãy đầu tư một chút thời gian vào tài liệu và nó sẽ đền đáp cho bạn sau này

Ví dụ về tài liệu Python

Hãy xem qua một số ví dụ về chuỗi tài liệu trong Python. Ví dụ: một hàm tầm thường bên dưới nhận hai biến và trả về tổng của chúng [theo mặc định] hoặc hiệu giữa chúng

def sum_subtract[a, b, operation="sum"]:
    if operation == "sum":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        print["Incorrect operation."]

print[sum_subtract[1, 2, operation="sum"]]

    3

Chức năng này khá đơn giản, nhưng để chứng minh sức mạnh của chuỗi tài liệu Python, hãy viết một số tài liệu

def sum_subtract[a, b, operation="sum"]:
    """
    Return sum or difference between the numbers 'a' and 'b'.
    The type of operation is defined by the 'operation' argument.
    If the operation is not supported, print 'Incorrect operation.'
    """
    if operation == "sum":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        print["Incorrect operation."]

Chuỗi tài liệu Python của hàm này được đặt giữa ba dấu ngoặc kép từ cả hai phía. Như bạn có thể thấy, chuỗi này giải thích chức năng này làm gì và cho biết cách chúng ta có thể thay đổi chức năng của nó — và điều gì xảy ra nếu nó không hỗ trợ hành động mà chúng ta muốn nó thực hiện. Đó là một ví dụ đơn giản và bạn có thể lập luận rằng chức năng này quá rõ ràng để yêu cầu bất kỳ lời giải thích nào, nhưng một khi các chức năng trở nên phức tạp và số lượng của chúng tăng lên, bạn sẽ cần ít nhất một số tài liệu để tránh bị lạc trong mã của chính mình

Điều gì đang xảy ra dưới mui xe? . Tất cả các gói tài liệu tốt đều có chuỗi tài liệu cho [gần như] tất cả các chức năng của chúng. Ví dụ: hãy xem DataFrame trong pandas

import pandas as pd

help[pd.DataFrame]

# Help on class DataFrame in module pandas.core.frame:

# class DataFrame[pandas.core.generic.NDFrame, pandas.core.arraylike.OpsMixin]
#  |  DataFrame[data=None, index: 'Axes | None' = None, columns: 'Axes | None' = None, dtype: 'Dtype | None' = None, copy: 'bool | None' = None]
#  |
#  |  Two-dimensional, size-mutable, potentially heterogeneous tabular data.
#  |
#  |  Data structure also contains labeled axes [rows and columns].
#  |  Arithmetic operations align on both row and column labels. Can be
#  |  thought of as a dict-like container for Series objects. The primary
#  |  pandas data structure.
#  |
#  |  Parameters
#  |  ----------
#  |  data : ndarray [structured or homogeneous], Iterable, dict, or DataFrame
#  |      Dict can contain Series, arrays, constants, dataclass or list-like objects. If
#  |      data is a dict, column order follows insertion-order. If a dict contains Series
#  |      which have an index defined, it is aligned by its index.
#  |
#  |      . versionchanged:: 0.25.0
#  |         If data is a list of dicts, column order follows insertion-order.
#  |
#  |  index : Index or array-like
#  |      Index to use for resulting frame. Will default to RangeIndex if
#  |      no indexing information part of input data and no index provided.
#  |  columns : Index or array-like
#  |      Column labels to use for resulting frame when data does not have them,
#  |      defaulting to RangeIndex[0, 1, 2, ..., n]. If data contains column labels,
#  |      will perform column selection instead.
#  |  dtype : dtype, default None
#  |      Data type to force. Only a single dtype is allowed. If None, infer.
#  |  copy : bool or None, default None
#  |      Copy data from inputs.
#  |      For dict data, the default of None behaves like ``copy=True``.  For DataFrame
#  |      or 2d ndarray input, the default of None behaves like ``copy=False``.
#  |
#  |      . versionchanged:: 1.3.0

# Docstring continues...

Bây giờ, nếu chúng ta xem mã nguồn của

    3

6, chúng ta sẽ thấy rằng

def sum_subtract[a, b, operation="sum"]:
    """
    Return sum or difference between the numbers 'a' and 'b'.
    The type of operation is defined by the 'operation' argument.
    If the operation is not supported, print 'Incorrect operation.'
    """
    if operation == "sum":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        print["Incorrect operation."]

1 cho chúng ta thấy chuỗi tài liệu của lớp

def sum_subtract[a, b, operation="sum"]:
    """
    Return sum or difference between the numbers 'a' and 'b'.
    The type of operation is defined by the 'operation' argument.
    If the operation is not supported, print 'Incorrect operation.'
    """
    if operation == "sum":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        print["Incorrect operation."]

2 [tìm kiếm

def sum_subtract[a, b, operation="sum"]:
    """
    Return sum or difference between the numbers 'a' and 'b'.
    The type of operation is defined by the 'operation' argument.
    If the operation is not supported, print 'Incorrect operation.'
    """
    if operation == "sum":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        print["Incorrect operation."]

3]

Về mặt kỹ thuật, chuỗi tài liệu được gán cho một thuộc tính được tạo tự động của đối tượng này có tên là

def sum_subtract[a, b, operation="sum"]:
    """
    Return sum or difference between the numbers 'a' and 'b'.
    The type of operation is defined by the 'operation' argument.
    If the operation is not supported, print 'Incorrect operation.'
    """
    if operation == "sum":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        print["Incorrect operation."]

4. Chúng ta cũng có thể in thuộc tính này ra và thấy rằng nó hoàn toàn giống như trước đây

    3

4

    3

5

Sự khác biệt giữa Tài liệu và Nhận xét mã

Sau khi chúng tôi đã thấy các chuỗi tài liệu trông như thế nào, đã đến lúc tìm hiểu lý do và cách chúng khác với các nhận xét mã thông thường. Ý tưởng chính là chúng [thường] phục vụ các mục đích khác nhau

Các tài liệu giải thích chức năng/lớp cần thiết để làm gì [i. e. , mô tả, đối số và đầu ra của nó — và bất kỳ thông tin hữu ích nào khác] trong khi nhận xét giải thích chức năng của các chuỗi mã cụ thể. Nói cách khác, nhận xét mã dành cho những người muốn sửa đổi mã và chuỗi tài liệu dành cho những người muốn sử dụng mã

Ngoài ra, nhận xét mã có thể hữu ích khi lập kế hoạch mã [ví dụ: bằng cách triển khai mã giả hoặc để lại nhận xét tạm thời về ý tưởng hoặc suy nghĩ của bạn không dành cho người dùng cuối]

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

Hãy xem xét các loại docstrings khác nhau. Đầu tiên, bạn nên duyệt qua các trang PEP của Python. Chúng ta có thể tìm thấy PEP 257, tóm tắt các tài liệu Python. Tôi thực sự khuyên bạn nên đọc tất cả mặc dù bạn có thể không hiểu tất cả. Các điểm thiết yếu như sau

1. Sử dụng ba dấu ngoặc kép để đính kèm các tài liệu
2. Chuỗi tài liệu kết thúc bằng dấu chấm
3. Nó sẽ mô tả lệnh của chức năng [i. e. , chức năng này làm gì, vì vậy chúng ta thường bắt đầu cụm từ bằng "Return…"]
4. Nếu chúng ta cần thêm nhiều thông tin hơn [ví dụ, về các đối số], thì chúng ta nên để một dòng trống giữa phần tóm tắt hàm/lớp và phần mô tả chi tiết hơn [sẽ nói thêm về điều này sau trong phần hướng dẫn]
5. Các tài liệu nhiều dòng vẫn ổn nếu chúng tăng khả năng đọc
6. Cần có một mô tả về các đối số, đầu ra, ngoại lệ, v.v.

Lưu ý rằng đây chỉ là những khuyến nghị và không phải là quy tắc nghiêm ngặt. Ví dụ: tôi nghi ngờ rằng chúng ta sẽ cần bổ sung thêm thông tin về các đối số hoặc đầu ra cho hàm

    3

9 vì bản tóm tắt đã đủ mô tả

Có bốn loại tài liệu chính, tất cả đều tuân theo các khuyến nghị trên

1. Tài liệu NumPy/SciPy
3. cấu trúc lại văn bản
4. văn bản

Bạn có thể xem tất cả chúng và quyết định cái nào bạn thích nhất. Các chuỗi tài liệu NumPy/SciPy và Google sẽ xuất hiện thường xuyên hơn mặc dù reStructuredText là kiểu tài liệu chính thức của Python

Hãy xem xét một tập dữ liệu trong thế giới thực và viết một hàm để áp dụng cho một trong các cột của nó

Bộ dữ liệu này chứa các trò chơi điện tử hàng đầu trên Metacritic trong giai đoạn 1995-2021

    3

7____18

Ví dụ: chúng tôi có thể quan tâm đến việc tạo một cột tính toán số ngày trước một trò chơi đã được phát hành. Với mục đích này, chúng tôi cũng sẽ sử dụng gói

def sum_subtract[a, b, operation="sum"]:
    """
    Return sum or difference between the numbers 'a' and 'b'.
    The type of operation is defined by the 'operation' argument.
    If the operation is not supported, print 'Incorrect operation.'
    """
    if operation == "sum":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        print["Incorrect operation."]

6 [hướng dẫn một, hướng dẫn hai]

Đầu tiên, hãy viết chức năng này và kiểm tra nó

def sum_subtract[a, b, operation="sum"]:
    if operation == "sum":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        print["Incorrect operation."]

print[sum_subtract[1, 2, operation="sum"]]

0

    3

0

Chức năng này hoạt động như dự định, nhưng tốt hơn là bổ sung cho nó bằng các chuỗi tài liệu. Trước hết, hãy sử dụng định dạng SciPy/NumPy

    3

1

Ở trên trong phần

def sum_subtract[a, b, operation="sum"]:
    """
    Return sum or difference between the numbers 'a' and 'b'.
    The type of operation is defined by the 'operation' argument.
    If the operation is not supported, print 'Incorrect operation.'
    """
    if operation == "sum":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        print["Incorrect operation."]

7, tôi không lặp lại [hầu hết] những gì đã có trong phần tóm tắt

Tiếp theo, một ví dụ về tài liệu của Google

    3

2

Một ví dụ về cấu trúc lại văn bản

    3

3

Cuối cùng, một ví dụ Epytext

    3

4

Hầu hết các chuỗi tài liệu chức năng phải có ít nhất một bản tóm tắt về chức năng, mô tả đầu vào và đầu ra của chúng. Hơn nữa, nếu chúng phức tạp hơn, chúng có thể bao gồm các ví dụ, ghi chú, ngoại lệ, v.v.

Cuối cùng, tôi không nói nhiều về các lớp vì chúng không thường xuyên xuất hiện trong khoa học dữ liệu, nhưng ngoài các phương thức [chức năng] của chúng bao gồm những gì, chúng cũng nên có những điều sau

1. mô tả thuộc tính
2. Danh sách các phương thức và tóm tắt chức năng của chúng
3. Giá trị mặc định của thuộc tính

Tài liệu kịch bản

Các tài liệu Python cũng mô tả chức năng và nguyên tắc sử dụng của các tập lệnh nhỏ, có thể phù hợp để tự động hóa một số tác vụ hàng ngày của chúng ta. Ví dụ: tôi thường xuyên cần đổi kroner Đan Mạch sang euro. Tôi có thể nhập một truy vấn trên Google mỗi lần hoặc tôi có thể tải xuống một ứng dụng có thể thực hiện điều đó cho tôi, nhưng tất cả dường như quá phức tạp và dư thừa. Tôi biết rằng một euro là khoảng 7. 45 krone Đan Mạch và vì tôi hầu như luôn làm việc trong thiết bị đầu cuối Linux, nên tôi quyết định viết một chương trình CLI nhỏ để chuyển đổi loại tiền này sang loại tiền khác

    3

5

Tập lệnh phải được ghi lại đầy đủ để cho phép người dùng áp dụng nó. Ở đầu tệp, một chuỗi tài liệu sẽ mô tả mục đích chính của tập lệnh, hướng dẫn ngắn gọn và các hàm hoặc lớp chứa trong đó. Ngoài ra, nếu bất kỳ gói của bên thứ ba nào được sử dụng, gói đó phải được nêu trong tài liệu để người dùng cài đặt gói đó trước khi sử dụng tập lệnh

Nếu bạn sử dụng mô-đun

def sum_subtract[a, b, operation="sum"]:
    """
    Return sum or difference between the numbers 'a' and 'b'.
    The type of operation is defined by the 'operation' argument.
    If the operation is not supported, print 'Incorrect operation.'
    """
    if operation == "sum":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        print["Incorrect operation."]

8 để tạo các ứng dụng CLI, thì mỗi đối số của nó phải được mô tả trong menu

def sum_subtract[a, b, operation="sum"]:
    """
    Return sum or difference between the numbers 'a' and 'b'.
    The type of operation is defined by the 'operation' argument.
    If the operation is not supported, print 'Incorrect operation.'
    """
    if operation == "sum":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        print["Incorrect operation."]

1 để người dùng cuối có thể chọn tùy chọn

import pandas as pd

0 và xác định đầu vào. Hơn nữa, tham số

import pandas as pd

1 phải được điền vào trong đối tượng

import pandas as pd

2

Cuối cùng, tất cả các chức năng phải được ghi lại đúng cách như đã mô tả trước đây. Ở đây, tôi đã bỏ qua các bộ mô tả "Đối số" và "Trả về" bởi vì, theo quan điểm của tôi, chúng không cần thiết

Ngoài ra, hãy lưu ý cách tôi sử dụng nhận xét mã và cách chúng khác với chuỗi tài liệu. Nếu bạn có một kịch bản bạn đã viết, hãy thêm vào đó một số tài liệu để thực hành

Lời khuyên chung về cách viết tài liệu và tài liệu Python

Khá rõ ràng tại sao tài liệu lại quan trọng và tại sao chuỗi tài liệu là một phần thiết yếu của tài liệu Python. Để kết thúc, hãy để tôi cung cấp cho bạn một số lời khuyên chung về tài liệu và chuỗi tài liệu Python

1. Viết tài liệu cho con người, không phải máy tính. Nó nên được mô tả nhưng ngắn gọn và đơn giản
2. Đừng lạm dụng docstrings. Đôi khi chúng không cần thiết và một chú thích mã nhỏ có thể đủ [hoặc thậm chí không có chú thích nào cả]. Giả sử rằng nhà phát triển có một số kiến ​​thức cơ bản về Python
3. Các tài liệu không nên giải thích cách thức hoạt động của hàm ẩn mà thay vào đó, cách sử dụng nó. Đôi khi, có thể cần phải giải thích cơ chế bên trong của một đoạn mã, vì vậy hãy sử dụng chú thích mã cho điều đó
4. Không sử dụng chuỗi tài liệu thay cho nhận xét và nhận xét thay cho mã

Tóm lược

Đây là những gì chúng ta đã học được trong hướng dẫn này

1. Tài liệu là một phần thiết yếu của dự án Python — nó quan trọng đối với người dùng cuối, nhà phát triển và bạn
2. Tài liệu là để sử dụng mã và nhận xét là để sửa đổi mã
3. PEP 257 tóm tắt các tài liệu Python
4. Có bốn định dạng chuỗi tài liệu chính. Các chuỗi tài liệu NumPy/SciPy, , reStructuredText và Epytext. Hai cái đầu tiên là phổ biến nhất
5. Một chuỗi tài liệu tập lệnh phải mô tả chức năng của tập lệnh, cách sử dụng và các chức năng có trong đó

Tôi hy vọng rằng bạn đã học được một cái gì đó mới ngày hôm nay. Vui lòng kết nối với tôi trên LinkedIn hoặc GitHub. Mã hóa vui vẻ

Khoa học dữ liệu hướng dẫn Python

Giới thiệu về tác giả

Artur Sannikov

Tôi là sinh viên Sinh học phân tử tại Đại học Padua, Ý quan tâm đến tin sinh học và phân tích dữ liệu

Làm cách nào để tạo chuỗi tài liệu trong Python?

Bạn có thể định dạng một chuỗi Python không?

Chuỗi tài liệu đi đâu?

__ doc __ nghĩa là gì trong Python?