Як вже вказувалося на інші відповіді тут, основний потік, ймовірно, йде шляхом Сфінкса, щоб згодом ви могли використовувати 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()
Ще один приклад тут, з невеликими деталями, документально підтвердженими:
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 вже вказувалося в іншому коментарі):
- Найголовніше, що параметри та їх документ завжди залишаються разом, що приносить наступні переваги:
- Менше набору тексту (не потрібно повторювати назву змінної)
- Легше обслуговування після зміни / видалення змінної. Після перейменування якогось параметра не буде жодного параграфа в документі-сироті.
- і простіше знайти пропущений коментар.
Зараз дехто може подумати, що цей стиль виглядає «потворно». Але я б сказав "потворне" - це суб'єктивне слово. Більш нейтральний спосіб сказати, що цей стиль не є мейнстрімом, тому він може виглядати вам менш звично, таким чином, менш комфортним. Знову ж таки, «комфортно» - це теж суб’єктивне слово. Але справа в тому, що всі переваги, описані вище, є об'єктивними. Ви не можете їх досягти, якщо слідувати стандартному шляху.
Сподіваємось, в якийсь день у майбутньому з'явиться інструмент генератора doc, який також може споживати такий стиль вбудованої форми. Це призведе до усиновлення.
PS: Ця відповідь випливає з мого власного вподобання використовувати вбудовані коментарі, коли я вважаю за потрібне. Я використовую один і той же стиль вбудовування для документування словника .