Làm thế nào để viết tài liệu có ý nghĩa?

Question

Điều gì, theo ý kiến ​​của bạn là một chuỗi có ý nghĩa? Bạn mong đợi điều gì được mô tả ở đó?

Ví dụ, hãy xem xét lớp Python này __init__:

def __init__(self, name, value, displayName=None, matchingRule="strict"): 
    """ 
    name - field name 
    value - field value 
    displayName - nice display name, if empty will be set to field name 
    matchingRule - I have no idea what this does, set to strict by default 
    """ 

Bạn có thấy ý nghĩa này? Đăng các ví dụ tốt/xấu của bạn để mọi người đều biết (và một câu trả lời chung để nó có thể được chấp nhận).

Answer 1

Tôi đồng ý với "Bất kỳ điều gì bạn không thể nói từ chữ ký của phương thức". Nó cũng có thể có nghĩa là để giải thích những gì một phương pháp/chức năng trả về.

Bạn cũng có thể muốn sử dụng Sphinx (và cú pháp reStructuredText) cho mục đích tài liệu bên trong tài liệu của bạn. Bằng cách đó bạn có thể bao gồm điều này trong tài liệu của bạn một cách dễ dàng. Để xem ví dụ, ví dụ: repoze.bfg sử dụng rộng rãi (example file, documentation example).

Một điều khác có thể đưa vào tài liệu cũng là doctests. Điều này có thể có ý nghĩa đặc biệt. cho mô-đun hoặc lớp học tài liệu như bạn cũng có thể hiển thị theo cách đó để sử dụng nó và có thể kiểm tra này cùng một lúc.

Answer 2

Điều gì nên đến đó:

Bất kỳ điều gì bạn không thể biết từ chữ ký của phương thức. Trong trường hợp này, bit chỉ hữu ích là: displayName - nếu trống sẽ được đặt thành tên trường.

Answer 3

Tôi thích sử dụng tài liệu để mô tả chi tiết nhất có thể chức năng, đặc biệt là hành vi trong trường hợp góc (trường hợp cạnh a.k.a.). Lý tưởng nhất, lập trình viên sử dụng hàm không bao giờ phải xem mã nguồn - trong thực tế, điều đó có nghĩa là bất cứ khi nào một lập trình viên khác phải xem mã nguồn để tìm ra một số chi tiết về cách hoạt động của hàm, chi tiết đó có lẽ đã được đề cập trong tài liệu. Như Freddy đã nói, mọi thứ không thêm bất kỳ chi tiết nào vào chữ ký của phương thức có lẽ không nên nằm trong chuỗi tài liệu.

Answer 4

Những điều nổi bật nhất mà tôi có thể nghĩ đến bao gồm trong chuỗi tài liệu là những thứ không rõ ràng. Thông thường, điều này bao gồm thông tin loại hoặc các yêu cầu về khả năng - ví dụ: "Yêu cầu một đối tượng giống như tập tin". Trong một số trường hợp, điều này sẽ hiển nhiên từ chữ ký, không phải như vậy trong các trường hợp khác.

Một điều hữu ích khác mà bạn có thể đưa vào tài liệu của mình là doctest.

Answer 5

Từ PEP 8:

ước để viết chuỗi tài liệu tốt (còn gọi là "docstrings") đang trở nên bất tử trong PEP 257.

• Viết docstrings cho tất cả các mô đun, hàm, lớp và phương thức công khai. Tài liệu không cần thiết cho các phương pháp phi công cộng, nhưng bạn cần có nhận xét mô tả những gì phương pháp thực hiện. Chú thích này sẽ xuất hiện sau dòng "def".
• PEP 257 mô tả các quy ước về chuỗi ngắn. Lưu ý rằng quan trọng nhất, "" "kết thúc một chuỗi tài liệu nhiều dòng phải nằm trên một dòng của chính nó, và tốt hơn là bắt đầu bởi một dòng trống.
• Đối docstrings lót, nó không quan trọng để giữ cho đóng """ trên cùng một dòng. Docstrings

Answer 6

Check-out NumPy của các ví dụ tốt (ví dụ http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).

Các docstrings được chia vào một số phần và trông giống như sau:

Compute the sum of the elements of a list. 

Parameters 
---------- 
foo: sequence of ints 
    The list of integers to sum up. 

Returns 
------- 
res: int 
    sum of elements of foo 

See also 
-------- 
cumsum: compute cumulative sum of elemenents 

Answer 7

Mục đích chung của việc thêm chuỗi tài liệu vào lúc bắt đầu chức năng là mô tả chức năng, những gì nó làm, wha nó sẽ trở lại và mô tả về các tham số. Bạn có thể thêm chi tiết triển khai nếu cần. Thậm chí bạn có thể thêm chi tiết về tác giả đã viết mã cho nhà phát triển trong tương lai.