Khi bắt gặp một chức năng mới, chúng ta thường cần tra cứu tài liệu của nó để tìm ra cách sử dụng nó. Ví dụ: chúng tôi bắt gặp chức năng
def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""1 tích hợp và chúng tôi biết rằng chúng tôi có thể kiểm tra địa chỉ bộ nhớ của một đối tượng. Tuy nhiên, rất có thể chúng ta không biết cách gọi hàm này. Ngoài việc tra cứu thông tin trực tuyến, có cách nào để có được thông tin thích hợp không?>>> help[id]
Help on built-in function id in module builtins:id[obj, /]
Return the identity of an object.
This is guaranteed to be unique among simultaneously existing objects.
[CPython uses the object's memory address.]
Trong Python, chúng ta có thể sử dụng hàm
def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""2 để truy xuất chuỗi tài liệu cho hàm def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""1. Từ góc độ chung, chúng tôi sử dụng chuỗi tài liệu để tham khảo tài liệu về hàm, lớp hoặc mô-đun. Trong trường hợp của chúng tôi ở đây, chúng tôi đang xem các chuỗi tài liệu cho chức năng này, cung cấp các hướng dẫn cụ thể về cách sử dụng def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""1. Điều quan trọng là các chuỗi tài liệu có thể truy cập được bằng một lệnh gọi trợ giúp đơn giản trong bảng điều khiển Python mà không cần dựa vào bất kỳ tài nguyên bên ngoài nào. Do đó, các tài liệu không chỉ cung cấp thông tin về cách sử dụng chức năng mà còn có thể truy cập thuận tiện. Trong bài viết này, chúng ta sẽ tìm hiểu cách viết các chuỗi tài liệu thích hợp cho một hàm trong PythonCấu trúc cơ bản
Chuỗi tài liệu của hàm là một chuỗi nhiều dòng nằm bên dưới phần đầu của hàm. Theo quy ước, chúng tôi sử dụng ba dấu ngoặc kép để bao quanh chuỗi. Bạn có thể sử dụng dấu ngoặc kép hoặc dấu ngoặc đơn để tạo thành dấu ngoặc kép miễn là chúng khớp với nhau
def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""Đối với chuỗi nhiều dòng này, cần có ba phần tử chính cùng với phần tử tùy chọn thứ tư
- Tóm tắt chức năng. Chức năng làm gì?
- Thông số. Những tham số nào được sử dụng trong hàm?
- Giá trị trả về. Hàm trả về loại dữ liệu nào?
- Ngoại lệ [Tùy chọn]. Những ngoại lệ có thể có mà chức năng có thể nâng cao?
Phong cách của Docstring
Chưa có sự đồng thuận về phong cách của chuỗi tài liệu trong Python. Ví dụ: như trong ảnh chụp màn hình bên dưới, một trong những IDE Python phổ biến nhất cung cấp 5 định dạng khác nhau. Plain, Epytext, reStructuredText [còn được gọi là reST], NumPy và Google
Các định dạng chuỗi tài liệu khác nhau được hỗ trợ bởi PyCharm
Trong số các định dạng này, định dạng mặc định là reST. Đoạn mã sau đây cho bạn thấy chuỗi tài liệu trông như thế nào đối với một hàm sử dụng reST
Chuỗi tài liệu ở định dạng reSTMột phong cách phổ biến khác là phong cách của Google, vì nó được Google chứng thực. một ví dụ đã được biểu diễn ở dưới
Chuỗi tài liệu ở định dạng GoogleMặc dù các định dạng khác nhau làm cho các chuỗi tài liệu trông khác nhau, nhưng các yếu tố cơ bản đều giống nhau. Trên thực tế, tùy thuộc vào từng lập trình viên để chọn phong cách ưa thích hoặc tuân theo quy ước của công ty. Đối với bài viết hiện tại, tôi sẽ sử dụng phong cách reST để hiển thị các ví dụ thích hợp
Tham số tài liệu và giá trị trả về
Tóm tắt của một chức năng nên đơn giản. Về bản chất, bạn nên nói cho người dùng biết chức năng đó làm gì một cách chính xác. Sau đó, bước tiếp theo là ghi lại từng tham số được sử dụng bởi hàm. Sử dụng kiểu reST, mỗi tham số bắt đầu bằng
def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""5 và các tham số khác nhau sẽ được liệt kê dưới dạng các dòng riêng biệt. Đối với mỗi tham số, chúng tôi cần cung cấp các thông tin sau- Tên. nó phải khớp chính xác với những gì được sử dụng trong phần đầu của hàm
- Loại. bạn đang mong đợi loại dữ liệu nào cho tham số?
- Sự miêu tả. tùy thuộc vào mức độ trực quan của tham số, hãy cung cấp mô tả hữu ích để giúp người dùng hiểu tham số này là gì hoặc tại sao tham số này lại cần thiết nếu mục đích của tham số không rõ ràng
- Giá trị mặc định [tùy chọn]. nếu tham số có giá trị mặc định, hãy chỉ định nó. Đáng chú ý, nếu người dùng mơ hồ về lý do tại sao một giá trị cụ thể được chọn làm giá trị mặc định, thì chúng tôi cần cung cấp giải thích ngắn gọn
Theo hướng dẫn này, hãy xem một chuỗi tài liệu với một ví dụ đơn giản
Tham số và giá trị trả về trong DocstringVí dụ trên cung cấp chuỗi tài liệu cần thiết cho ba tham số, bao gồm tên, loại và giải thích tương ứng của chúng. Ngoài ra, vì
def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""6 có giá trị mặc định nên nó cũng được đề cập trong chuỗi tài liệu. Khi chuỗi tài liệu của một tham số mở rộng nhiều hơn một dòng, hãy nhớ chèn một số thụt đầu dòng cho dòng thứ hai và trên đó để phân định rõ ràng giữa các tham số khác nhauĐối với giá trị trả về của hàm, chuỗi tài liệu sử dụng
def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""7 để chỉ ra loại giá trị trả về và giải thích. Lời giải phải ngắn gọn, dễ hiểuChỉ định bất kỳ ngoại lệ có thể
Khi chức năng của bạn đưa ra bất kỳ ngoại lệ nào, bạn nên chỉ định chúng trong chuỗi tài liệu sao cho khi người dùng đọc chuỗi tài liệu, họ biết các ngoại lệ có thể xảy ra để họ có thể tránh hoặc xử lý chúng
Chúng ta hãy xem xét hàm
def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""0, bao gồm phép toán chia. def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""1. Chúng tôi biết rằng một phép chia không được xác định nếu số chia là 0 và chúng tôi có thể thấy điều gì sẽ xảy ra nếu chúng tôi đang cố gắng chia một số cho số không>>> 1 / 0
Traceback [most recent call last]:
File “”, line 1, in
ZeroDivisionError: division by zeroVì vậy, chúng ta nên chỉ định một ngoại lệ như vậy trong chuỗi tài liệu, như được hiển thị bên dưới
Chỉ định ngoại lệNhư được hiển thị ở trên, chúng tôi kiểm tra rõ ràng xem số chia có phải là 0 hay không và tăng
def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""2 khi nó bằng 0. Xin lưu ý rằng ngay cả khi chúng tôi không đưa ra ngoại lệ này một cách rõ ràng, thì ngoại lệ đó vẫn có thể được đưa ra khi chúng tôi gọi một cái gì đó như def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""3, bởi vì Python tăng def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""2 bất cứ khi nào có thể. Ở đây, tôi nêu rõ ngoại lệ này vì tôi muốn chỉ cho bạn cách một ngoại lệ do hàm đưa ra sẽ được ghi lại trong chuỗi tài liệu như thế nàoPhần kết luận
Trong bài viết này, chúng tôi đã tìm hiểu về cách cung cấp chuỗi tài liệu cho một chức năng, điều này sẽ giúp người dùng hiểu rõ hơn về chức năng của bạn. Họ có thể chỉ cần gọi
def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""5 để truy xuất tài liệu của hàm. Ngoài ra, một hàm có một thuộc tính đặc biệt được gọi là def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""6 và bạn có thể gọi def the_function[]:
"""the docstring
goes here, as a multi-line string
below the head
"""7 để hiển thị chuỗi tài liệu của hàmĐối với một chức năng, chuỗi tài liệu của nó phải bao gồm ba thành phần thiết yếu. tóm tắt một câu, tham số [tên, loại, giải thích và giá trị mặc định nếu được đặt] và giá trị trả về [loại và giải thích]. Nếu chức năng có thể đưa ra ngoại lệ, thì nó cũng phải được chỉ định
Có nhiều kiểu khác nhau để tạo chuỗi tài liệu của hàm. Điều quan trọng là gắn bó với một phong cách cụ thể một cách nhất quán. Ví dụ: nếu bạn làm việc theo nhóm, hãy sử dụng phong cách mà nhóm của bạn đã thống nhất. Nếu bạn chỉ viết các hàm/mô-đun cho chính mình, hãy áp dụng phong cách mà bạn quen thuộc nhất