Il mainstream è, come già indicato in altre risposte, probabilmente seguendo la via Sfinge in modo che tu possa usare Sphinx per generare quei documenti fantasiosi in seguito.
Detto questo, vado personalmente con lo stile di commento in linea di tanto in tanto.
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()
Un altro esempio qui, con alcuni piccoli dettagli documentati in linea:
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
I vantaggi (come già sottolineato da @ mark-horvath in un altro commento) sono:
- Ancora più importante, i parametri e il loro documento rimangono sempre insieme, il che porta i seguenti vantaggi:
- Meno digitazione (non è necessario ripetere il nome della variabile)
- Manutenzione più semplice quando si cambia / rimuove la variabile. Non ci sarà mai alcun paragrafo del documento dei parametri orfani dopo aver rinominato alcuni parametri.
- e più facile trovare commenti mancanti.
Ora, alcuni potrebbero pensare che questo stile sembri "brutto". Ma direi "brutto" è una parola soggettiva. Un modo più neutrale è dire che questo stile non è mainstream, quindi potrebbe sembrare meno familiare, quindi meno comodo. Ancora una volta, "comodo" è anche una parola soggettiva. Ma il punto è che tutti i vantaggi sopra descritti sono obiettivi. Non puoi raggiungerli se segui il modo standard.
Spero che un giorno in futuro, ci sarà uno strumento di generazione di documenti che può anche consumare uno stile così in linea. Ciò guiderà l'adozione.
PS: Questa risposta deriva dalla mia preferenza di usare commenti in linea ogni volta che lo ritengo opportuno. Uso lo stesso stile in linea anche per documentare un dizionario .