Docstring trong Python và hàm help()
Bài 7/17 · Chương 8
Hàm
- 8 phút
- Cơ bản
- Python 3.14
- Cập nhật
Trong bài này · 12
Docstring trong Python là chuỗi mô tả viết ở dòng đầu tiên của thân hàm, nói hàm làm gì, nhận gì và trả về gì. Bạn viết docstring cho những hàm sẽ dùng lại, để vài tuần sau mở code ra, hay khi người khác gọi hàm của bạn, chỉ cần gõ help() là đọc được cách dùng mà không phải đọc lại từng dòng.
Cần biết trước: hàm và def, lệnh return và chuỗi ba nháy.
Viết docstring ngay dưới dòng def
Hàm tính tiền dưới đây có một chuỗi ba nháy đứng ngay dưới dòng def, trước các câu lệnh khác. Chuỗi đó là docstring. Python cất nó vào tên __doc__ gắn với hàm, viết tinh_tien.__doc__, nên đọc lại được lúc chương trình đang chạy:
def tinh_tien(don_gia, so_ly=1):
"""Trả về tiền của một món: đơn giá nhân số ly."""
return don_gia * so_ly
print(tinh_tien(29000, 2))
print(tinh_tien.__doc__)KẾT QUẢ
58000
Trả về tiền của một món: đơn giá nhân số ly.Docstring không đổi việc hàm làm: lời gọi vẫn trả về 58000. Một chuỗi đứng một mình trên một dòng không làm gì cả, trừ khi nó là dòng đầu của thân hàm. Ở vị trí đó Python giữ nó lại làm tài liệu. Dùng một cặp nháy kép cũng được, nhưng quy ước chung là ba nháy kép, kể cả khi docstring chỉ có một dòng, để sau này viết thêm dòng không phải đổi dấu nháy. Docstring giống nhãn dán trên lọ gia vị: ai cầm lọ lên cũng đọc được, không cần mở nắp.
Đọc tài liệu bằng help()
Hàm help() nhận một hàm làm đối số và in ra tài liệu của nó: dòng chữ ký với tên các tham số và giá trị mặc định, rồi tới docstring. Lời gọi chỉ ghi tên hàm, không có cặp ngoặc tròn sau tên đó, vì bạn đưa chính hàm cho help() chứ không gọi nó:
def tinh_tien(don_gia, so_ly=1):
"""Trả về tiền của một món: đơn giá nhân số ly."""
return don_gia * so_ly
help(tinh_tien)KẾT QUẢ
Help on function tinh_tien in module __main__:
tinh_tien(don_gia, so_ly=1)
Trả về tiền của một món: đơn giá nhân số ly.Dòng đầu cho biết hàm được định nghĩa trong chương trình đang chạy (__main__). Dòng chữ ký lấy thẳng từ dòng def, nên bạn không cần chép tên tham số vào docstring. Đổi so_ly=1 thành so_ly=2 rồi chạy lại: dòng chữ ký in tinh_tien(don_gia, so_ly=2).
Hàm có sẵn của Python cũng có docstring, chỉ là viết bằng tiếng Anh:
help(len)KẾT QUẢ
Help on built-in function len in module builtins:
len(obj, /)
Return the number of items in a container.Dấu / trong chữ ký nói obj chỉ truyền được theo vị trí, cách viết mà bài tham số chỉ theo vị trí giải thích. Gặp một hàm lạ trong code của người khác, gọi help() trên nó là cách nhanh để biết nó cần gì.
Docstring nhiều dòng
Hàm có nhiều tham số hoặc trả về nhiều giá trị cần nói nhiều hơn một câu. Docstring nhiều dòng gồm một dòng tóm tắt, một dòng trống, rồi phần giải thích:
def doi_phut(tong_phut):
"""Đổi một số phút ra giờ và phút.
tong_phut là số nguyên không âm, như thời lượng một bộ phim.
Trả về hai số: số giờ trọn và số phút còn lại.
"""
return tong_phut // 60, tong_phut % 60
print(doi_phut(135))
help(doi_phut)KẾT QUẢ
(2, 15)
Help on function doi_phut in module __main__:
doi_phut(tong_phut)
Đổi một số phút ra giờ và phút.
tong_phut là số nguyên không âm, như thời lượng một bộ phim.
Trả về hai số: số giờ trọn và số phút còn lại.Dòng tóm tắt đứng riêng vì nhiều công cụ chỉ hiện dòng đó, như hộp gợi ý của trình soạn thảo khi bạn gõ tên hàm. Phần giải thích nói điều chữ ký không nói được: tham số mang nghĩa gì, giá trị trả về gồm những gì. help() bỏ phần thụt lề chung của các dòng, nên docstring thụt theo thân hàm vẫn in ra gọn. Hai cặp ba nháy đóng mở trên dòng riêng khi docstring dài hơn một dòng.
Docstring còn chứa được ví dụ gọi hàm viết sau dấu nhắc >>>, và module doctest chạy các ví dụ đó để kiểm hàm còn đúng không. Bài doctest dạy cách viết và chạy chúng.
Viết gì trong một docstring
Docstring tốt trả lời câu hỏi của người gọi hàm, không kể lại từng dòng code. Ba điều đáng có: hàm làm việc gì, mỗi tham số mang nghĩa gì khi tên chưa đủ rõ, và hàm trả về gì, kể cả trường hợp đặc biệt như trả về None:
def tim_mon(menu, ten_mon):
"""Tìm giá của một món trong menu.
menu là list các cặp (tên món, giá).
Trả về giá của món, hoặc None khi menu không có món đó.
"""
for ten, gia in menu:
if ten == ten_mon:
return gia
return None
menu = [("cà phê sữa", 29000), ("trà đào", 35000)]
print(tim_mon(menu, "trà đào"), tim_mon(menu, "bạc xỉu"))KẾT QUẢ
35000 NoneNgười đọc docstring này biết phải kiểm tra None trước khi cộng tiền, mà không cần đọc vòng lặp. Khi sửa hàm, sửa docstring cùng lúc: docstring nói sai còn hại hơn không có, vì người gọi tin nó. Kiểu của tham số và giá trị trả về còn ghi được ngay trên dòng def, gọi là type hints, bài ngay sau bài này.
Kiểm tra nhanh
Trong ví dụ viết mô tả bằng comment, nếu đổi dòng cuối thành
print(tinh_tien.__doc__, tinh_tien(30000))thì in ra gì?None 3000030000 30000# Trả về tiền của một món: đơn giá nhân số ly. 30000
Mỗi dòng dưới đây là dòng đầu tiên của thân một hàm, phía sau còn câu lệnh
return. Những dòng nào cho hàm một docstring?# Trả về phí giao hàng."""Trả về phí giao hàng.""""Trả về phí giao hàng."phi = 30000
Với hàm
tinh_tien(don_gia, so_ly=1)có docstring của bài,help(tinh_tien)in ra những gì?- Toàn bộ code của hàm, kể cả dòng
return - Dòng chữ ký
tinh_tien(don_gia, so_ly=1)rồi docstring - Kết quả của lời gọi
tinh_tienvới đối số mặc định
- Toàn bộ code của hàm, kể cả dòng
Điền tên hàm in ra tài liệu của hàm
doi_phut:____(doi_phut)
Bài tập
Đổi comment thành docstring cho hàm xếp loại
Hàm xep_loai(diem) mới có một comment mô tả. Đổi comment đó thành docstring, giữ nguyên câu chữ, rồi viết thân hàm: điểm từ 8 là "Giỏi", từ 6.5 là "Khá", còn lại là "Trung bình".
Ví dụ: xep_loai(8.5) trả về "Giỏi", xep_loai(6.4) trả về "Trung bình".
Trả về: tên hạng, một str.
def xep_loai(diem):
# Xếp loại: Giỏi từ 8, Khá từ 6.5, còn lại Trung bình.
pass # Viết thân hàm thay cho dòng nàyTóm tắt
Docstring là chuỗi đứng ở dòng đầu tiên của thân hàm; quy ước viết bằng ba nháy kép.
Python cất docstring vào
__doc__; hàm không có docstring thì__doc__làNone.Comment, hay chuỗi đứng sau một câu lệnh khác, không được Python giữ làm docstring.
help(ten_ham)in dòng chữ ký lấy từdefrồi docstring; truyền tên hàm, không gọi hàm.Docstring nhiều dòng: dòng tóm tắt, dòng trống, rồi nghĩa của tham số và giá trị trả về.
Câu hỏi thường gặp
Docstring khác comment trong Python ở chỗ nào?
Comment dành cho người đọc file code, Python bỏ nó đi khi chạy. Docstring là một chuỗi Python giữ lại cùng hàm, nên help(), trình soạn thảo và công cụ tạo tài liệu đọc được. Docstring nói hàm làm gì cho người gọi hàm, comment giải thích một dòng khó cho người sửa hàm.
Hàm help() trong Python dùng thế nào ở cửa sổ dòng lệnh?
Trong chế độ tương tác, gõ help(len) để đọc tài liệu của một hàm. Tài liệu dài thì hiện từng trang: bấm phím cách để xem tiếp, bấm q để thoát. Gõ help() không có đối số thì Python mở trình tra cứu riêng, gõ quit để quay lại.
Docstring nên viết bằng tiếng Việt hay tiếng Anh?
Theo người sẽ đọc code. Dự án của một nhóm nói tiếng Việt viết docstring tiếng Việt được, Python lưu chuỗi tiếng Việt có dấu bình thường. Thư viện chia sẻ rộng thường viết tiếng Anh, giống docstring của các hàm có sẵn. Chọn một cách và giữ nguyên trong cả dự án.
Có quy ước chung cho cách viết docstring không?
Có, PEP 257 của cộng đồng Python (peps.python.org/pep-0257, xem ngày 14/11/2026) nói về ba nháy kép, dòng tóm tắt và dòng trống phía sau như bài này làm. Quy ước trình bày code nói chung nằm ở PEP 8, bài PEP 8 và ruff dạy kỹ.
Chủ đề
Bài này có hữu ích?
Hỏi đáp
Tham vấn chuyên môn
Nhà sáng lập AIDev và VietPlatform · Thạc sĩ AI MSE
- Tốt nghiệp thủ khoa xuất sắc Thạc sĩ AI MSE.
- Đồng sáng lập, CTO E-University, SVOnline: số hóa 10+ đại học, 40.000+ sinh viên.
- Xây hệ thống AI cho doanh nghiệp tại VietPlatform.