主流は、ここで他の回答がすでに指摘したように、おそらくスフィンクスの方法で進んでいますを使用して、Sphinxを使用してこれらの豪華なドキュメントを後で生成できるすることです。
そうは言っても、私は時々インラインコメントスタイルで行きます。
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()
ここにもう1つの例を示します。小さな詳細がインラインで文書化されています。
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
（@ mark-horvathが別のコメントですでに指摘したように）利点は次のとおりです。
- 最も重要なのは、パラメーターとそのドキュメントが常に一緒にあることです。
- 入力が少ない（変数名を繰り返す必要がない）
- 変数の変更/削除時のメンテナンスが容易になります。一部のパラメーターの名前を変更した後、孤立したパラメータードキュメントの段落はありません。
- 不足しているコメントを見つけやすくなります。
さて、このスタイルは「醜い」と思われるかもしれません。しかし、「醜い」とは主観的な言葉だと思います。より控えめな言い方をすると、このスタイルは主流ではないため、見慣れないものになり、快適さが低下する可能性があります。繰り返しになりますが、「快適」も主観的な言葉です。しかし、要点は、上記のすべての利点は客観的であるということです。標準的な方法に従えば達成できません。
うまくいけば、将来的には、そのようなインラインスタイルも使用できるドキュメントジェネレータツールが提供される予定です。それが採用を促進します。
PS：この答えは、自分が適切だと思うときはいつでもインラインコメントを使用するという私の個人的な好みに基づいています。辞書を文書化するために同じインラインスタイルを使用していますます。