La corriente principal es, como ya señalaron otras respuestas aquí, probablemente siguiendo la forma de Sphinx para que pueda usar Sphinx para generar esos documentos elegantes más adelante.
Dicho esto, personalmente voy con el estilo de comentario en línea de vez en cuando.
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 ejemplo más aquí, con algunos pequeños detalles documentados en línea:
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
Los beneficios (como @ mark-horvath ya señaló en otro comentario) son:
- Lo más importante, los parámetros y su documento siempre permanecen juntos, lo que trae los siguientes beneficios:
- Menos tipeo (no es necesario repetir el nombre de la variable)
- Mantenimiento más fácil al cambiar / eliminar variables. Nunca habrá algún párrafo de documento de parámetro huérfano después de cambiar el nombre de algún parámetro.
- y más fácil de encontrar comentarios faltantes.
Ahora, algunos pueden pensar que este estilo se ve "feo". Pero yo diría que "feo" es una palabra subjetiva. Una forma más neutral es decir que este estilo no es convencional, por lo que puede parecerle menos familiar y, por lo tanto, menos cómodo. Nuevamente, "cómodo" es también una palabra subjetiva. Pero el punto es que todos los beneficios descritos anteriormente son objetivos. No puede lograrlos si sigue el camino estándar.
Esperemos que algún día en el futuro, haya una herramienta de generación de documentos que también pueda consumir ese estilo en línea. Eso impulsará la adopción.
PD: Esta respuesta se deriva de mi preferencia de usar comentarios en línea siempre que lo considero conveniente. También uso el mismo estilo en línea para documentar un diccionario .