Những gì để đặt trong một mô-đun python mô-đun? [đóng cửa]

Ok, vì vậy tôi đã đọc cả PEP 8 và PEP 257 , và tôi đã viết rất nhiều tài liệu cho các hàm và lớp, nhưng tôi không chắc chắn về những gì nên đi trong một chuỗi mô-đun. Tôi đã tìm ra, ở mức tối thiểu, nó nên ghi lại các chức năng và các lớp mà mô-đun xuất ra, nhưng tôi cũng đã thấy một vài mô-đun liệt kê tên tác giả, thông tin bản quyền, v.v. Có ai có một ví dụ về cách một chuỗi con trăn tốt nên được cấu trúc?

Hãy suy nghĩ về ai đó đang làm help(yourmodule)tại lời nhắc của phiên dịch viên tương tác - họ muốn biết điều gì? (Các phương pháp trích xuất và hiển thị thông tin khác gần tương đương với helplượng thông tin). Vì vậy, nếu bạn có trong x.py:

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

sau đó:

>>> import x; help(x)

trình diễn:

Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'Blah' objects>
     |      list of weak references to the object (if defined)

Như bạn thấy, thông tin chi tiết về các lớp (và các hàm cũng vậy, mặc dù tôi không hiển thị ở đây) đã được bao gồm trong các tài liệu của các thành phần đó; Chuỗi tài liệu riêng của mô-đun nên mô tả chúng rất tổng thể (nếu có) và tập trung vào một bản tóm tắt ngắn gọn về toàn bộ mô-đun có thể làm gì cho bạn, lý tưởng với một số ví dụ được chứng minh (giống như các hàm và các lớp lý tưởng nên có các ví dụ được chứng minh trong tài liệu của họ).

Tôi không thấy siêu dữ liệu như tên tác giả và bản quyền / giấy phép giúp người dùng mô-đun như thế nào - nó có thể đi vào bình luận, vì nó có thể giúp ai đó xem xét liệu có nên sử dụng lại hoặc sửa đổi mô-đun hay không.

Để báo giá các thông số kỹ thuật :

Chuỗi tài liệu của tập lệnh (chương trình độc lập) có thể được sử dụng làm thông điệp "sử dụng" của nó, được in khi tập lệnh được gọi với các đối số không chính xác hoặc bị thiếu (hoặc có thể với tùy chọn "-h", cho "trợ giúp"). Một chuỗi tài liệu như vậy sẽ ghi lại chức năng của cú pháp và cú pháp dòng lệnh, biến môi trường và tệp. Thông báo sử dụng có thể khá phức tạp (một số màn hình đầy đủ) và đủ để người dùng mới sử dụng lệnh đúng cách, cũng như tham chiếu nhanh đầy đủ đến tất cả các tùy chọn và đối số cho người dùng tinh vi.

Chuỗi doc cho một mô-đun thường liệt kê các lớp, ngoại lệ và hàm (và bất kỳ đối tượng nào khác) được mô-đun xuất ra, với một bản tóm tắt một dòng của mỗi mô-đun. (Các tóm tắt này thường cung cấp ít chi tiết hơn dòng tóm tắt trong chuỗi tài liệu của đối tượng.) Chuỗi tài liệu cho một gói (nghĩa là chuỗi tài liệu của __init__.pymô-đun của gói ) cũng nên liệt kê các mô-đun và gói con được gói.

Chuỗi doc cho một lớp nên tóm tắt hành vi của nó và liệt kê các phương thức công khai và các biến thể hiện. Nếu lớp dự định được phân lớp và có giao diện bổ sung cho các lớp con, giao diện này sẽ được liệt kê riêng (trong chuỗi doc). Trình xây dựng lớp nên được ghi lại trong chuỗi doc cho __init__phương thức của nó . Các phương thức riêng lẻ phải được ghi lại bằng chuỗi doc riêng của chúng.

Chuỗi doc của hàm hoặc phương thức là cụm từ kết thúc trong một khoảng thời gian. Nó quy định hiệu ứng của hàm hoặc phương thức là một lệnh ("Thực hiện điều này", "Trả lại"), không phải như một mô tả; ví dụ: không viết "Trả về tên đường dẫn ...". Một chuỗi đa dòng cho một hàm 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ố của nó, giá trị trả về, các tác dụng phụ, các 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.