Wie andere Antworten hier bereits dargelegt haben, geht der Mainstream wahrscheinlich mit der Sphinx-Methode einher, sodass Sie Sphinx verwenden können, um diese ausgefallenen Dokumente später zu generieren.
Davon abgesehen gehe ich gelegentlich gelegentlich mit Inline-Kommentaren um.
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()
Ein weiteres Beispiel hier mit einigen winzigen Details, die inline dokumentiert sind:
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
Die Vorteile (wie @ mark-horvath bereits in einem anderen Kommentar hervorgehoben hat) sind:
- Am wichtigsten ist, dass Parameter und ihr Dokument immer zusammen bleiben, was die folgenden Vorteile bringt:
- Weniger tippen (Variablenname muss nicht wiederholt werden)
- Einfachere Wartung beim Ändern / Entfernen der Variablen. Nach dem Umbenennen eines Parameters wird es niemals einen verwaisten Parameter-Doc-Absatz geben.
- und leichter, fehlende Kommentare zu finden.
Nun mögen einige denken, dass dieser Stil "hässlich" aussieht. Aber ich würde sagen, "hässlich" ist ein subjektives Wort. Eine neutralere Art ist zu sagen, dass dieser Stil kein Mainstream ist, so dass er Ihnen weniger vertraut und daher weniger bequem erscheint. Auch hier ist "bequem" ein subjektives Wort. Der Punkt ist jedoch, dass alle oben beschriebenen Vorteile objektiv sind. Sie können sie nicht erreichen, wenn Sie dem Standardweg folgen.
Hoffentlich wird es eines Tages ein Dokumentgenerator-Tool geben, das auch einen solchen Inline-Stil verwenden kann. Das wird die Adoption vorantreiben.
PS: Diese Antwort ergibt sich aus meiner eigenen Präferenz, Inline-Kommentare zu verwenden, wann immer ich es für richtig halte. Ich verwende den gleichen Inline-Stil, um auch ein Wörterbuch zu dokumentieren .