Разметка имен аргументов в комментариях функций

Question

Одна из самых распространенных дилемм, которые возникают у меня при комментировании кода, - как размечать имена аргументов. Я объясню, что я имею в виду:

def foo(vector, widht, n=0):
  """ Transmogrify vector to fit into width. No more than n 
      elements will be transmogrified at a time
  """

Теперь моя проблема в том, что имена аргументов vector, width и n никак не различаются в этом комментарии и могут быть перепутаны с простым текстом. Некоторые другие варианты:

Transmogrify 'вектор', чтобы вписаться в «Ширина». Не более 'n'

Или, может быть:

Transmogrify -vector-, чтобы соответствовать -width-. Не более -n-

Или даже:

Transmogrify: vector: вписывается в : Ширина :. Не более: n:

Вы поняли. Некоторые инструменты, такие как Doxygen, навязывают это, но что, если я не использую инструмент? Этот язык зависит?

Что вы предпочитаете использовать?

Answer 1

Я лично предпочитаю одинарные кавычки - ваш первый пример. Кажется, ближе всего к тому, как на некоторые названия / именованные объекты можно ссылаться в английском тексте, когда ни подчеркивание, ни курсив отсутствуют.

Answer 2

Мой любимый вариант - написать:

<code>def foo(vector, width, n=0):
  """ Transmogrify 'vector' to fit into 'width'. No more than 'n' 
      elements will be transmogrified at a time

      @param vector: list of something
      @param width:  int
      @keyword n:      int (default 0)
  """

Epydoc распознает @param (см. Руководство по Epydoc ), и вы можете использовать некоторое необычное регулярное выражение, чтобы найти и напечатать параметры вашей функции, и, надеюсь, Eclipse начнет показывать описание параметров для функций Python в быстрой подсказке когда-нибудь, и я почти уверен, что это будет следовать шаблону

@ <keyword> <paramName> <colon> </code> 

В любом случае, когда придет тот день, будет легко заменить @param на @ everythingElse.

Answer 3

В любом случае не используйте ни один, а просто введите имена переменных в тексте. Или я пишу весь текст так, что он объясняет, что делает функция, но не упоминает параметры в ней. Это в том случае, когда значение параметров должно стать понятным само по себе, когда вы поймете, что делает функция.

Answer 4

Я согласен с Рувимом: первый пример наиболее читабелен.

Конечно, это зависит от ваших личных навыков чтения. Если вы привыкли читать комментарии в стиле вашего третьего примера, вы можете найти этот стиль наиболее читабельным.

Но первый стиль наиболее близок к тому, как мы читаем и пишем текст в повседневной жизни (газеты, книги). Поэтому его будет легче читать тем, у кого нет опыта чтения ваших комментариев.