Пишем комментарии в Python правильно (примеры кода)

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

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

Комментарии — это способ объяснить то, что делает программа верхнего уровня. Это отмеченные строки, которые комментируют код. В Python есть два типа: однострочные и многострочные.

Что такое однострочные комментарии в Python?

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

# Хороший код документируется

print("Изучите Python шаг за шагом!")

Когда разработчик или тестер добавляет однострочный комментарий, ему необходимо удостовериться в том, что отступ у него такой же, как и у кода. Например, требуется оставить комментарий к строке объявления функции, не имеющей отступа. Тем не менее, есть блоки, которые имеют такой отступ. Чтобы было понятно, к чему относится комментарий, необходимо его также делать с соответствующим отступом.  

# Создадим список месяцев

months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',

                'Jul','Aug','Sep','Oct','Nov','Dec']




# Функция вывода календарных месяцев

def showCalender(months):

    # Цикл for проходит по списку и вводит название каждого месяца

    for month in months:

        print(month)




showCalender(months)

Использование многострочных комментариев в Python

Python дает возможность указывать комментарии в несколько строк. Их называют многополосными или блочными. Этот тип подходит для описания чего-то более сложного.

Он необходим для того, чтобы описать происходящее во всем следующем коде. Ниже приведен пример многострочных комментариев в Python.

Использование символа #

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

Такой тип многострочных комментариев – это просто совокупность нескольких однострочных. 

К слову, в оригинале символ «решетка» называется octothorpe. Если перевести это слово с латинского, то получится «восемь концов». Впервые этот термин был придуман группой инженеров в Bell Labs, работавшая над созданием первой клавиатуры с сенсорным управлением.

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

# 1. Знать синтаксис, типы данных, структуры и условные операторы.

# 2. Изучить обработку ошибок и ввод/вывод.

# 3. Читайте о продвинутых структурах данных.

# 4. Пишите функции и следуйте концепциям ООП.




def main():

    print("Начнем изучать Python.")

Что такое docstring в Python?

С помощью docstring (далее их мы будем также называть строками документации) разработчики Python могут добавлять комментарии для каждого модуля, функции, метода либо класса.

Чтобы их задать, необходимо воспользоваться специальной строковой константой. Она должна быть первой инструкцией в определении объекта.

Вообще, docstring используется не только в качестве своеобразной альтернативы комментарию. Они описывают, что делает функция, но не используется для того, чтобы объяснять, как она делается.

Настоятельно рекомендуется их добавлять в каждую функцию программы.

Что делать для того, чтобы задать docstring в Python?

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

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

В чем отличия между комментариями и docstring?

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

Чтобы получить доступ к docstring, необходимо использовать такой метод. 

myobj.__doc__.

Приведем пример кода, который наглядно демонстрирует это. 

def theFunction():

    '''

    Эта функция демонстрирует использование docstring в Python.

    '''

    print("docstring python не являются комментариями.")




print("\nВыведем docstring функции...")

print(theFunction.__doc__)

Чем комментарии могут помочь разработчику?

С помощью комментариев можно добиться сразу нескольких положительных эффектов:

1. Возможность ускорить попытки разработаться в коде. Если в приложении появилась ошибка, то и для разработчика, и для тестировщика, важно понимать, что вообще должна делать эта программа. А если код писался полгода назад, то всегда можно благополучно забыть о том, что там должна делать программа. Чтобы не допустить таких неприятных ситуаций, и используются комментарии.
2. Комментарии не дают запутаться в логике приложения. Разработчик может создавать новые библиотеки, функции, переменные. Чтобы было проще понять, что какие значат, используются комментарии.
3. Комментарии объясняют результат работы программы во время ее отладки или проверки. Это надо тестировщикам.
4. С помощью комментариев другой человек может получить детальное описание сложных алгоритмов и формул, что позволяет разобраться в коде тем, кто не разбирается в этой области. Например, если в программе используются сложные математические, физические либо экономические расчеты. Ну или другие сложные вычисления.

К слову, комментарии используются не только в Python, а вообще в любом языке программирования. Даже если синтаксис русскоязычный, как в 1С или ДРАКОН. Может показаться, что и без комментариев понятно, что делает приложение, но это опасное заблуждение. Забыть можно код на любом языке, пусть на русском, пусть на английском, пусть на Python, пусть на C++.

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

Каких правил нужно придерживаться?

Чтобы не плодить бесконечное количество ненужных строк кода, разработчики используют несколько простых правил при комментировании:

1. Писать комментарии нужно прямо над кодом, к которому они относятся. Это позволит сразу понимать, что делает тот или иной код. В ином случае пришлось бы сначала знакомиться с кодом, а потом уже понимать, что он делает. Это неудобно, и придется тратить дополнительное время на то, чтобы во всем этом разбираться. Если пояснения вообще короткие, их можно писать справа. 
2. Все базовые элементы кода нужно комментировать: модули, функции, константы, глобальные переменные, классы и так далее.
3. Нельзя лить воду в комментариях. Необходимо писать коротко и лаконично. Если смысловой нагрузки в комментариях нет, это раздражает того, кто знакомится с кодом. Поэтому нельзя писать фраз типа «это гениальный код», «таблица 1» и других подобных.
4. Запрещено использовать в коде слова, которые могут кого-то оскорбить. Немного непонятное требование для жителя страны из постсоветского блока. Но этому правилу решила последовать Twitter, которая в своем коде убрала слова slave, master и blacklist.

Как автоматизировать создание комментариев?

Это отдельная тема для обсуждения, но в паре слов мы рассмотрим то, как правильно автоматизировать создание комментариев. В разных IDE, которые разработаны в последнее время, такая возможность предусмотрена. Для этого используются теги, которые начинаются с символа @. Наиболее популярными являются следующие комментарии.

• @author — идентифицирует автора исходного кода;
• @param — определяет параметр метода;
• @see — ссылка;
• @since — версия программного обеспечения;
• @return — тип возвращаемых процедурой или функцией данных.

Такие комментарии позволяют автоматически формировать документацию программы. Чтобы это сделать, используются автоматические генераторы документации. Для Python такой программой является Epydoc.

Принцип работы таких приложений простой. Генератор осуществляет обработку файла с исходным кодом, находит там имена классов, свойств и так далее, а потом их связывает с тегами. 

Выводы

Комментарии и строки документации повышают ценность программы. Они делают код более читабельным и простым в обслуживании. Даже с рефакторингом с комментариями будет намного проще.

Разработка программного обеспечения — это всего лишь 10% кода. Остальные 90% — поддержка.

Поэтому всегда добавляйте содержательные комментарии и строки документации, поскольку они упрощают процесс взаимодействия и ускоряют процесс рефакторинга.

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