Główny nurt jest, jak już wskazały inne odpowiedzi, prawdopodobnie idąc drogą Sfinksa , abyś mógł użyć Sfinksa do późniejszego wygenerowania tych wymyślnych dokumentów.
Biorąc to pod uwagę, osobiście od czasu do czasu używam stylu komentowania w tekście.
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()
Jeszcze jeden przykład, z kilkoma drobnymi szczegółami udokumentowanymi w tekście:
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
Korzyści (jak @ mark-horvath wskazał już w innym komentarzu) to:
- Co najważniejsze, parametry i ich doc zawsze pozostają razem, co przynosi następujące korzyści:
- Mniej wpisywania (nie ma potrzeby powtarzania nazwy zmiennej)
- Łatwiejsza konserwacja po zmianie / usunięciu zmiennej. Po zmianie nazwy jakiegoś parametru nigdy nie będzie jakiegoś osieroconego akapitu dokumentu dotyczącego parametrów.
- i łatwiej znaleźć brakujący komentarz.
Niektórzy mogą pomyśleć, że ten styl wygląda „brzydko”. Ale powiedziałbym, że „brzydki” to subiektywne słowo. Bardziej neutralnym sposobem jest stwierdzenie, że ten styl nie jest głównym nurtem, więc może wyglądać mniej znajomo, a przez to mniej komfortowo. Ponownie „wygodne” jest również subiektywnym słowem. Chodzi o to, że wszystkie opisane powyżej korzyści są obiektywne. Nie możesz ich osiągnąć, jeśli podążasz standardową drogą.
Miejmy nadzieję, że któregoś dnia w przyszłości pojawi się narzędzie do generowania dokumentów, które również będzie obsługiwać taki styl wbudowany. To będzie napędzać adopcję.
PS: Ta odpowiedź wynika z moich własnych preferencji dotyczących używania komentarzy w tekście, kiedy tylko uznam to za stosowne. Używam tego samego stylu wbudowanego do dokumentowania słownika .