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

Question

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

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

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

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

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

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

Answer 1

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

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

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

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

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

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

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

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

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

Answer 2

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

Answer 3

Я думаю, что только первый строковый литерал в определении (или классе) является «специальным», т. Е. Переводится в интерпретатор в определенный объект (или класс) строка документа .

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

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