Dòng chính là, như các câu trả lời khác ở đây đã chỉ ra, có thể đi theo cách Sphinx để bạn có thể sử dụng Sphinx để tạo các tài liệu ưa thích đó sau này.
Điều đó đang được nói, cá nhân tôi thỉnh thoảng đi với phong cách bình luận nội tuyến.
def complex( # Form a complex number
real=0.0, # the real part (default 0.0)
imag=0.0 # the imaginary part (default 0.0)
): # Returns a complex number.
"""Form a complex number.
I may still use the mainstream docstring notation,
if I foresee a need to use some other tools
to generate an HTML online doc later
"""
if imag == 0.0 and real == 0.0:
return complex_zero
other_code()
Một ví dụ nữa ở đây, với một số chi tiết nhỏ được ghi lại trong dòng:
def foo( # Note that how I use the parenthesis rather than backslash "\"
# to natually break the function definition into multiple lines.
a_very_long_parameter_name,
# The "inline" text does not really have to be at same line,
# when your parameter name is very long.
# Besides, you can use this way to have multiple lines doc too.
# The one extra level indentation here natually matches the
# original Python indentation style.
#
# This parameter represents blah blah
# blah blah
# blah blah
param_b, # Some description about parameter B.
# Some more description about parameter B.
# As you probably noticed, the vertical alignment of pound sign
# is less a concern IMHO, as long as your docs are intuitively
# readable.
last_param, # As a side note, you can use an optional comma for
# your last parameter, as you can do in multi-line list
# or dict declaration.
): # So this ending parenthesis occupying its own line provides a
# perfect chance to use inline doc to document the return value,
# despite of its unhappy face appearance. :)
pass
Những lợi ích (như @ mark-horvath đã chỉ ra trong một bình luận khác) là:
- Quan trọng nhất, các tham số và tài liệu của chúng luôn ở cùng nhau, mang lại những lợi ích sau:
- Gõ ít hơn (không cần lặp lại tên biến)
- Bảo trì dễ dàng hơn khi thay đổi / loại bỏ biến. Sẽ không bao giờ có một đoạn doc tham số mồ côi sau khi bạn đổi tên một số tham số.
- và dễ dàng hơn để tìm thấy bình luận bị thiếu.
Bây giờ, một số người có thể nghĩ rằng phong cách này trông "xấu xí". Nhưng tôi sẽ nói "xấu xí" là một từ chủ quan. Một cách trung lập hơn để nói, phong cách này không phải là chủ đạo nên nó có thể trông ít quen thuộc hơn với bạn, do đó ít thoải mái hơn. Một lần nữa, "thoải mái" cũng là một từ chủ quan. Nhưng vấn đề là, tất cả những lợi ích được mô tả ở trên là khách quan. Bạn không thể đạt được chúng nếu bạn làm theo cách tiêu chuẩn.
Hy vọng một ngày nào đó trong tương lai, sẽ có một công cụ tạo tài liệu cũng có thể sử dụng kiểu nội tuyến như vậy. Điều đó sẽ thúc đẩy việc áp dụng.
PS: Câu trả lời này bắt nguồn từ sở thích sử dụng bình luận nội tuyến của tôi bất cứ khi nào tôi thấy phù hợp. Tôi sử dụng cùng một kiểu nội tuyến để ghi lại một từ điển .