Câu trả lời:
Cách chính xác để làm điều đó là cung cấp một chuỗi. Bằng cách đó, help(add)cũng sẽ nhổ ra nhận xét của bạn.
def add(self):
"""Create a new user.
Line 2 of comment...
And so on...
"""
Đó là ba trích dẫn kép để mở bình luận và ba trích dẫn kép khác để kết thúc nó. Bạn cũng có thể sử dụng bất kỳ chuỗi Python hợp lệ nào. Nó không cần phải là multiline và dấu ngoặc kép có thể được thay thế bằng dấu ngoặc đơn.
Xem: PEP 257
Sử dụng một chuỗi doc :
Một chuỗi ký tự xuất hiện dưới dạng câu lệnh đầu tiên trong một mô-đun, hàm, lớp hoặc định nghĩa phương thức. Một chuỗi như vậy trở thành
__doc__thuộc tính đặc biệt của đối tượng đó.Tất cả các mô-đun thường phải có tài liệu và tất cả các chức năng và lớp được xuất bởi một mô-đun cũng nên có tài liệu. Các phương thức công khai (bao gồm cả hàm
__init__tạo) cũng cần có các tài liệu. Một gói có thể được ghi lại trong chuỗi mô-đun của__init__.pytệp trong thư mục gói.Chuỗi ký tự xuất hiện ở nơi khác trong mã Python cũng có thể đóng vai trò là tài liệu. Chúng không được nhận ra bởi trình biên dịch mã byte Python và không thể truy cập dưới dạng các thuộc tính đối tượng thời gian chạy (nghĩa là không được gán cho
__doc__), nhưng hai loại tài liệu bổ sung có thể được trích xuất bằng các công cụ phần mềm:
- Chuỗi ký tự xuất hiện ngay sau khi gán đơn giản ở cấp cao nhất của mô-đun, lớp hoặc
__init__phương thức được gọi là "tài liệu thuộc tính".- Chuỗi ký tự xảy ra ngay sau khi một chuỗi khác được gọi là "tài liệu bổ sung".
Vui lòng xem PEP 258 , "Thông số thiết kế của Docutils" [2] , để biết mô tả chi tiết về thuộc tính và các tài liệu bổ sung ...
Các nguyên tắc bình luận tốt là khá chủ quan, nhưng đây là một số hướng dẫn:
Đọc về việc sử dụng docstrings trong mã Python của bạn.
Theo quy ước chuỗi Python :
Chuỗi tài liệu cho một chức năng hoặc phương thức nên tóm tắt hành vi của nó và ghi lại các đối số, giá trị trả về, tác dụng phụ, ngoại lệ được nêu ra và các hạn chế về thời điểm có thể được gọi (tất cả nếu có thể). Đối số tùy chọn nên được chỉ định. Nó nên được ghi lại cho dù các đối số từ khóa là một phần của giao diện.
Sẽ không có quy tắc vàng, mà thay vào đó cung cấp các nhận xét có ý nghĩa gì đó cho các nhà phát triển khác trong nhóm của bạn (nếu bạn có) hoặc thậm chí với chính mình khi bạn quay lại sau sáu tháng.
Tôi sẽ đi một bước xa hơn là chỉ nói "sử dụng một chuỗi". Chọn một công cụ tạo tài liệu, chẳng hạn như pydoc hoặc epydoc (tôi sử dụng epydoc trong pyparsing) và sử dụng cú pháp đánh dấu được công cụ đó nhận ra. Chạy công cụ đó thường xuyên trong khi bạn đang phát triển, để xác định các lỗ hổng trong tài liệu của bạn. Trong thực tế, bạn thậm chí có thể được hưởng lợi từ việc viết các tài liệu cho các thành viên của một lớp trước khi thực hiện lớp.
Sử dụng docstrings .
Đây là quy ước được đề xuất tích hợp trong PyCharm cho các nhận xét mô tả chức năng:
def test_function(p1, p2, p3):
"""
my function does blah blah blah
:param p1:
:param p2:
:param p3:
:return:
"""def)? (Không phải là một câu hỏi tu từ.)
Mặc dù tôi đồng ý rằng đây không phải là một nhận xét, mà là một chuỗi doc như hầu hết các câu trả lời (tất cả?) Đề xuất, tôi muốn thêm numpydoc (một hướng dẫn kiểu doc doc ) .
Nếu bạn làm như vậy, bạn có thể (1) tự động tạo tài liệu và (2) mọi người nhận ra điều này và có thời gian dễ dàng hơn để đọc mã của bạn.
Bạn có thể sử dụng ba trích dẫn để làm điều đó.
Bạn có thể sử dụng dấu ngoặc đơn:
def myfunction(para1,para2):
'''
The stuff inside the function
'''Hoặc trích dẫn kép:
def myfunction(para1,para2):
"""
The stuff inside the function
"""