Комментарии Python: # против строк

Что касается стандартного способа размещения комментариев внутри исходного кода Python:

def func():
    "Func doc"
    ... <code>
    'TODO: fix this'
    #badFunc()
    ... <more code>

def func():
    "Func doc"
    ... <code>
    #TODO: fix this
    #badFunc()
    ... <more code>

Я предпочитаю писать общие комментарии как строки вместо префикса #. В официальном руководстве по стилю Python не упоминается использование строк в качестве комментариев (если я не пропустил его при чтении).

Мне нравится это в основном потому, что я думаю, что символ # выглядит уродливым с блоками комментариев. Насколько я знаю, эти строки ничего не делают.

Есть ли недостатки в этом?

Ответ 1

Не злоупотребляйте строками (операторы no-op) в качестве комментариев. Докстры, например. первая строка в модуле, классе или функции, специальная и определенно рекомендуется.

Обратите внимание, что docstrings - это документация, а документация и комментарии - две разные вещи!

Документация важна для понимания того, что делает код.
Комментарии объясняют, как это делает код.

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

Использование строк для комментариев имеет следующие (потенциальные) недостатки:

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

Самое важное для программистов на Python: это не pythonic:

Должен быть один - и желательно только один - простой способ сделать это.

Придерживайтесь стандартов, используйте комментарии.

Ответ 2

Недостатком, конечно же, является то, что кто-то другой, читающий его, обнаружит, что строки кода и строки комментариев чередуются, что может сбить с толку.

Ответ 3

Я думаю, что только первый строковый литерал в определении (или классе) является "особым", т.е. хранится интерпретатором в определенный объект (или класс) docstring.

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

Конечно, я не сравнивал это, а также не знаю переводчика Python достаточно хорошо, чтобы сказать наверняка.