Hướng dẫn chung mà bạn đang tìm kiếm nằm ngay trong số PEP257 trong nội dung bạn đã trích dẫn, có thể bạn chỉ cần xem nó đang hoạt động.
Chức năng của bạn là một ứng cử viên tốt cho một một dòng docstring ("trường hợp thực sự rõ ràng"):
def script_running(self, script):
"""Check if the script is running."""
Thông thường nếu bạn nói rằng một chức năng đang kiểm tra một cái gì đó nó có nghĩa là nó sẽ quay trở lại True hoặc False, nhưng nếu bạn thích bạn có thể cụ thể hơn:
def script_running(self, script):
"""Return True if the script is running, False otherwise."""
một lần nữa tất cả trong một dòng.
Tôi cũng có thể thay đổi tên chức năng của bạn, vì không cần nhấn mạnh vào chức năng hoạt động trong tên của nó (tập lệnh). Tên hàm phải là cái gì đó ngọt ngào, ngắn gọn và có ý nghĩa về chức năng của hàm. Có lẽ tôi sẽ đi với:
def check_running(self, script):
"""Return True if the script is running, False otherwise."""
Đôi khi function-name-tưởng tượng là mệt mỏi bởi tất cả các mã hóa, nhưng bạn nên cố gắng nào để làm tốt nhất của bạn.
Đối với một ví dụ multiline, cho tôi mượn một docstring từ google guidelines:
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""Fetches rows from a Bigtable.
Retrieves rows pertaining to the given keys from the Table instance
represented by big_table. Silly things may happen if
other_silly_variable is not None.
Args:
big_table: An open Bigtable Table instance.
keys: A sequence of strings representing the key of each table row
to fetch.
other_silly_variable: Another optional variable, that has a much
longer name than the other args, and which does nothing.
Returns:
A dict mapping keys to the corresponding table row data
fetched. Each row is represented as a tuple of strings. For
example:
{'Serak': ('Rigel VII', 'Preparer'),
'Zim': ('Irk', 'Invader'),
'Lrrr': ('Omicron Persei 8', 'Emperor')}
If a key from the keys argument is missing from the dictionary,
then that row was not found in the table.
Raises:
IOError: An error occurred accessing the bigtable.Table object.
"""
Đây có thể là một cách để "tóm tắt hành vi của nó và ghi lại lập luận, giá trị trả về (s), tác dụng phụ của nó, 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ó) ".
Bạn cũng có thể quan tâm để xem điều này example of pypi project rằng nó có nghĩa là phải được ghi lại bằng Sphinx.
My 2 cents: Hướng dẫn có nghĩa là để cung cấp cho bạn một ý tưởng về những gì bạn nên và không nên làm, nhưng họ không quy định nghiêm ngặt mà bạn phải nhắm mắt làm theo. Vì vậy, ở cuối chọn những gì bạn cảm thấy tốt hơn.
Tôi muốn xóa cái gì đó đang được nói trong một câu trả lời về cách nhấn tối đa Đường dây dài với một docstring.
PEP8 nói với bạn "Hạn chế tất cả các dòng đến tối đa là 79 ký tự" mặc dù vào cuối ai cũng làm 80.
này là 80 charachters:
--------------------------------------------------------------------------------
Và điều này có thể một trường hợp cạnh có một câu dài một chút là tất cả những gì bạn thực sự cần:
def my_long_doc_function(arg1, arg2):
"""This docstring is long, it's a little looonger than the 80 charachters
limit.
"""
Giống như một dòng docstring, có nghĩa là cho các trường hợp thực sự rõ ràng, nhưng trên trình soạn thảo của bạn (với giới hạn 80 charachter) là trên nhiều dòng.