Как обернуть и выровнять комментарии в коде Python

python emacs comments alignment wrap

1589 просмотра

4 ответа

Я пытаюсь сделать мой код на Python более читабельным. Я прочитал руководство по стилю, но я не знаю, как получить что-то подобное

x = foo(x);  # compute the value of the next prime number
             # that is larger than x  (foo is a really bad 
             # choice for this function's name) 

или это

x = x + 1                 # Compensate for border
some other code           # some other comment

Как вы оберните комментарий и выровняете их так? Вы не просто набираете кучу space, не так ли? Что, если я отредактировал код, нужно ли заново выравнивать комментарии вручную?

Я использую Emacs в качестве моего редактора.

Автор: LWZ Источник Размещён: 17.05.2019 03:05

Ответы (4)


8 плюса

Решение

Я не думаю, что вы хотите этого вообще. Lattyware уже объяснил второй случай, но давайте посмотрим на первый:

x = foo(x);  # compute the value of the next prime number
             # that is larger than x  (foo is a really bad 
             # choice for this function's name) 

Комментарии, которые слишком длинны, чтобы поместиться в строку, могут быть превращены в блочные комментарии над кодом, например:

# compute the value of the next prime number that is larger than
# x (foo is a really bad choice for this function's name)
x = foo(x);

Это кажется более читабельным, чем выровненные по праву комментарии. Это также дает вам больше места. И с emacs определенно проще (просто наберите все это и мета-Q). И, цитируя встроенные комментарии в PEP 8:

Используйте встроенные комментарии экономно.

Встроенный комментарий - это комментарий в той же строке, что и оператор.

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

Кроме того, пока мы говорим о PEP 8:

  • «Комментарии должны быть полными предложениями». Ваш первый комментарий требует периодов. (Да, он также говорит: «Если комментарий короткий, точка в конце может быть опущена», но у вас есть двухстрочный комментарий из 3-х строк, поэтому здесь это не применимо.)
  • «Если комментарий является фразой или предложением, его первое слово должно быть написано с большой буквы». Итак, используйте «Compute» (но не «foo», потому что это идентификатор).
  • Не добавляйте комментарий о неправильном названии функции, просто переименуйте функцию.
  • Избавьтесь от этой точки с запятой.

Так:

# Compute the value of the next prime number that is larger than x.
x = next_larger_prime(x)

Но как только вы это сделаете, вам даже не понадобится комментарий.

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

Автор: abarnert Размещён: 18.01.2013 11:38

3 плюса

Я бы сказал, что эти два случая очень разные. В первом случае я бы использовал пробелы над вкладками, так как вы хотите, чтобы комментарии выравнивались независимо от настроек ширины вкладок в редакторе пользователя. Очевидно, что если вы используете табуляцию для отступа в коде нормально, используйте вкладки, пока не достигнете уровня кода, затем пробелы.

Представьте себе использование вкладок:

x = foo(x) # compute the value of the next prime number
⟶⟶⟶⟶ # that is larger than x  (foo is a really bad 
⟶⟶⟶⟶ # choice for this function's name) 

Теперь представьте, что кто-то использует более короткую настройку для длины вкладки:

x = foo(x) # compute the value of the next prime number
→→→→ # that is larger than x  (foo is a really bad 
→→→→ # choice for this function's name) 

Однако я бы сказал, что вы можете заменить это строкой с тройными кавычками:

"""Compute the value of the next prime number
that is larger than x  (foo is a really bad 
choice for this function's name)."""
x = foo(x)

Во втором случае я не думаю, что выравнивание комментариев повышает удобочитаемость, я бы просто поместил их в конец строки. PEP-8 не рекомендует выравнивать назначения, литералы dict и т. Д. - и я бы счел это расширением.

x = x + 1 # Compensate for border
some other code # some other comment
Автор: Gareth Latty Размещён: 18.01.2013 11:32

2 плюса

Вы не должны этого делать. Первый должен быть отформатирован так:

# Compute the value of the next prime number that is larger than x
# (foo is a really bad choice for this function's name).
x = foo(x)

И второе:

x = x + 1  # Compensate for border
some other code   # some other comment
Автор: Daniel Roseman Размещён: 18.01.2013 11:37

0 плюса

Несмотря на причины использования альтернатив, если вы когда-нибудь окажетесь в такой ситуации, когда вам это нужно, скажем, для комментирования строк доказательства, написанного на псевдокоде-Python, вы можете использовать align-regexp:

M-x align-regexp RET  # RET

(поставьте пробел перед знаком #) следует делать то, что вы просили. Работает на выбранном в данный момент регионе.

Автор: serv-inc Размещён: 15.02.2019 08:48
Вопросы из категории :
32x32