Основное направление, как уже указывалось в других ответах, вероятно, связано с Sphinx, чтобы вы могли использовать 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 в другом комментарии):
- Самое главное, что параметры и их документ всегда остаются вместе, что дает следующие преимущества:
- Меньше ввода (нет необходимости повторять имя переменной)
- Более простое обслуживание при изменении/удалении переменной. После того, как вы переименуете какой-либо параметр, никогда не будет абзаца документа с потерянным параметром.
- и легче найти недостающий комментарий.
Некоторые могут подумать, что этот стиль выглядит «уродливым». Но я бы сказал, что «уродливый» — это субъективное слово. Более нейтральный способ сказать, что этот стиль не является мейнстримом, поэтому он может показаться вам менее знакомым и, следовательно, менее удобным. Опять же, «удобно» — тоже субъективное слово. Но дело в том, что все преимущества, описанные выше, объективны. Вы не сможете их достичь, если пойдете стандартным путем.
Надеюсь, когда-нибудь в будущем появится инструмент для создания документов, который также может использовать такой встроенный стиль. Это будет способствовать усыновлению.
PS: этот ответ получен из моего собственного предпочтения использования встроенных комментариев всякий раз, когда я считаю нужным. Я использую тот же встроенный стиль для документирования словаря.
person
RayLuo
schedule
19.09.2016
