Nói chung, thêm tài liệu luôn là một cách thực hành tốt trong khi tạo bất kỳ dự án nào. Trong Python cũng vậy, chúng ta có thể thêm tài liệu vào các hàm, lớp hoặc phương thức lớp để chúng ta biết chức năng của chúng bằng cách đọc tài liệu. Tài liệu như vậy trong Python được gọi là docstring.
Xác định một chuỗi tài liệu trong Python
Chuỗi tài liệu được tạo bằng cách thêm một chuỗi được đặt trong ba dấu nháy đơn
def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
9 hoặc ba dấu nháy kép def cube[x]:
"""Returns the cube of the argument x.
Argument: x must be a number
Returns: cube of x
"""
return x**3
print[cube[2]]
0. Chúng được viết ngay sau định nghĩa của hàm hoặc lớpChuỗi đơn dòng Python
Đây là các tài liệu được xác định trong một dòng
Hãy xem một ví dụ về chuỗi tài liệu một dòng
def cube[x]:
'''Returns the cube of the argument x.'''
return x**3
print[cube[2]]
Như bạn có thể thấy, bằng cách đọc chuỗi tài liệu, chúng ta có thể biết hàm này làm gì. Do đó, các chuỗi tài liệu phải được viết sao cho chúng ta hiểu chức năng tổng thể của hàm chỉ bằng cách đọc nó
Ví dụ tương tự được viết bằng cách sử dụng ba dấu ngoặc kép bên dưới
def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
Chúng ta nên thực hiện các thực hành sau trong khi viết các tài liệu dòng đơn
- Dấu ngoặc kép mở và đóng phải nằm trên cùng một dòng
- Chuỗi tài liệu phải bắt đầu bằng chữ in hoa và kết thúc bằng dấu chấm [. ]
- Không được để trống dòng nào trước và sau chuỗi tài liệu
- Chuỗi tài liệu một dòng phù hợp hơn cho các chức năng nhỏ và ít phức tạp hơn
Chuỗi tài liệu đa dòng Python
Đây là những tài liệu kéo dài thành nhiều dòng
Hãy xem một ví dụ về chuỗi tài liệu một dòng
def cube[x]:
"""Returns the cube of the argument x.
Argument: x must be a number
Returns: cube of x
"""
return x**3
print[cube[2]]
Chúng ta nên thực hiện các thực hành sau trong khi viết các tài liệu dòng đơn
- Chuỗi tài liệu phải bắt đầu bằng một dòng tóm tắt, sau đó là một dòng trống, tiếp theo là các chi tiết khác
- Dòng tóm tắt của chuỗi tài liệu có thể nằm trên cùng một dòng với ba dấu ngoặc kép mở đầu hoặc trên dòng tiếp theo
- Ba dấu ngoặc kép đóng phải nằm trên một dòng mới sau khi nội dung chuỗi tài liệu kết thúc
- Các tài liệu nhiều dòng phù hợp hơn cho các lớp hoặc các chức năng phức tạp hơn
Bây giờ chúng ta đã được giới thiệu về chuỗi tài liệu, hãy xem cách viết chuỗi tài liệu nhiều dòng cho các hàm và lớp
Tài liệu Python cho hàm
Đối với các chức năng nhỏ, nên viết một chuỗi tài liệu dòng đơn. Đối với các chức năng phức tạp và lớn hơn, nên viết chuỗi tài liệu nhiều dòng
Cần ghi nhớ những điểm sau đây khi viết các chuỗi tài liệu nhiều dòng cho các hàm hoặc phương thức lớp
- Chuỗi tài liệu phải bao gồm một bản tóm tắt [tốt nhất là một bản tóm tắt lót] nêu rõ mục tiêu của chức năng. Các đối số và giá trị trả về cùng với kiểu dữ liệu của chúng cũng phải được đưa vào chuỗi tài liệu
- Nó cũng nên liệt kê các ngoại lệ được nêu ra
def divide[a, b]:
"""Divides two numbers and returns the quotient.
Args:
a [int]: An integer
b [int]: A non-zero integer
Raises:
ValueError: b should not be 0
Returns:
quotient [float]: quotient of the division of a by b
"""
if b == 0:
raise ValueError[]
quotient = a/b
return quotient
print[divide[10, 2]]
Bạn có thể thấy rằng chúng tôi đã bao gồm một mô tả ngắn về chức năng của hàm khi bắt đầu chuỗi tài liệu. Chúng tôi cũng đã bao gồm thông tin về các đối số, ngoại lệ được đưa ra và giá trị trả về
Truy cập chuỗi hàm
Khi chúng ta thêm một chuỗi tài liệu vào một hàm, nó sẽ được thêm dưới dạng thuộc tính
def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
0 của hàm. Do đó, để truy cập chuỗi tài liệu của một hàm, chúng ta cần truy cập thuộc tính def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
0 của nódef divide[a, b]:
"""Divides two numbers and returns the quotient.
Args:
a [int]: An integer
b [int]: A non-zero integer
Raises:
ValueError: b should not be 0
Returns:
quotient [float]: quotient of the division of a by b
"""
if b == 0:
raise ValueError[]
quotient = a/b
return quotient
print[divide.__doc__]
Chia hai số và trả về thương
lập luận
một [int]. Một số nguyên
b [int]. Một số nguyên khác không
tăng
Giá trịError. b không nên là 0
trả lại
thương số [phao]. thương của phép chia a cho b
Chúng tôi đã truy cập chuỗi tài liệu của hàm chia bằng cách viết
def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
2Tài liệu Python cho các lớp học
Hãy xem xét những điểm cần được xem xét khi viết docstrings cho các lớp học
- Chuỗi tài liệu nên bao gồm một bản tóm tắt [tốt nhất là một bản tóm tắt lót] nêu rõ hành vi của lớp. Nó cũng nên bao gồm tất cả các thuộc tính
- Nếu lớp kế thừa một lớp khác, thì nên bao gồm các chi tiết về siêu lớp của nó. Ngoài ra, nếu bất kỳ phương thức nào của lớp đang ghi đè một phương thức của siêu lớp của nó, thì nên bao gồm các chi tiết của phương thức đó
- Hàm tạo và các phương thức bên trong lớp phải có các tài liệu riêng biệt
________số 8
Chúng tôi đã thêm các chuỗi tài liệu riêng cho lớp, hàm tạo và phương thức của nó. Trong chuỗi tài liệu của lớp, chúng tôi đã bao gồm một bản tóm tắt về lớp cùng với các chi tiết của các thuộc tính
Truy cập chuỗi tài liệu của các lớp, hàm tạo và phương thức
Cũng giống như các hàm, nếu một chuỗi tài liệu được thêm vào một lớp, nó sẽ được thêm dưới dạng thuộc tính
def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
0 của nó. Do đó, chuỗi tài liệu của lớp Hình chữ nhật có thể được truy cập dưới dạng
def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
4. Chuỗi tài liệu của hàm tạo của nó có thể được truy cập dưới dạng def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
5 và phương thức của nó def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
6 dưới dạng def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
7Hãy in tất cả các chuỗi tài liệu này trong ví dụ trước
def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
4**** Chuỗi tài liệu của lớp Hình chữ nhật ****
Lớp Rectangle lưu kích thước của hình chữ nhật
Thuộc tính
chiều dài [phao]. Chiều dài của hình chữ nhật
chiều rộng [phao]. Chiều rộng của hình chữ nhật
**** Chuỗi tài liệu của lớp hàm tạo Hình chữ nhật ****
Hàm tạo để khởi tạo đối tượng
lập luận
tôi [phao]. Chiều dài của hình chữ nhật
b [thả nổi]. Chiều rộng của hình chữ nhật
**** Chuỗi tài liệu của phương thức getArea của lớp Hình chữ nhật ****
Trả về diện tích của đối tượng Rectangle
Đối với các lớp, chúng ta cũng có thể sử dụng hàm
def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
8 để đọc các chuỗi tài liệu. Hàm này đọc các tài liệu của lớp và các phương thức của nó. Ví dụ, để đọc các chuỗi tài liệu của lớp Rectangle và các phương thức của nó, chúng ta cần viết def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
9Hãy in các chuỗi tài liệu trong ví dụ trước bằng cách sử dụng
def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
8def cube[x]:
"""Returns the cube of the argument x."""
return x**3
print[cube[2]]
8Trợ giúp về lớp Hình chữ nhật trong mô-đun __main__
lớp Hình chữ nhật [nội trang. vật]
. Hình chữ nhật[l, b]
.
. Lớp Rectangle lưu kích thước của hình chữ nhật
.
. Thuộc tính
. chiều dài [phao]. Chiều dài của hình chữ nhật
. chiều rộng [phao]. Chiều rộng của hình chữ nhật
.
. Các phương thức được định nghĩa ở đây
.
. __init__[tự, l, b]
. Hàm tạo để khởi tạo đối tượng
.
. lập luận
. tôi [phao]. Chiều dài của hình chữ nhật
. b [thả nổi]. Chiều rộng của hình chữ nhật
.
. getArea[bản thân]
. Trả về diện tích của đối tượng Rectangle
.
. --------------------------------------------------
. Bộ mô tả dữ liệu được xác định tại đây
.
. __dict__
. từ điển cho các biến thể hiện [nếu được xác định]
.
. __điểm yếu__
. danh sách các tham chiếu yếu đến đối tượng [nếu được xác định]
Thật tốt khi có các chuỗi tài liệu trong mã của bạn để việc hiểu chức năng và thuộc tính của các hàm và lớp của bạn trở nên dễ dàng hơn bất cứ khi nào bạn hoặc người khác xem qua mã. Vì vậy, hãy bắt đầu đưa chúng vào chương trình của bạn
Để học từ các video đơn giản, bạn luôn có thể xem khóa học video Python của chúng tôi trên CodesDope Pro. Nó có hơn 500 câu hỏi thực hành và hơn 20 dự án