Комментирование кода в Python

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

В этом руководстве мы расскажем о том, что такое комментарии в Python, зачем они нужны и как их правильно использовать.

Что такое комментарии в коде Python

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

В Python комментарии могут выполнять различные задачи:

• улучшать читаемость кода;
• объяснять назначение и логику строк;
• предотвращать выполнение лишнего кода (используя закомментирование);
• давать подсказки и пояснения по дальнейшей работе;
• помогать быстро восстанавливать в памяти важные моменты.

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

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

Синтаксис комментариев в Python

В Python комментарии начинаются с символа #, после которого следует описание. 

Например:

print("Hello, World!") #Код выводит в консоль строку "Hello, World!"

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

Еще один пример показывает, как # можно использовать для объяснения значения переменных:

x = 10  # Присваиваем переменной x значение 10

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

Пример комментирования кода 

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

В качестве примера рассмотрим код, который создает таблицу для хранения логинов и паролей в базе данных SQLite:

db_lp = sqlite3.connect('login_password.db')

cursor_db = db_lp.cursor()
sql_create = '''CREATE TABLE passwords(
login TEXT PRIMARY KEY,
password TEXT NOT NULL);'''

cursor_db.execute(sql_create)
db_lp.commit()

cursor_db.close()
db_lp.close()

Понять структуру и логику этого кода может быть сложно даже опытному программисту. 

Но его можно сделать более понятным, если прописать комментарии:

db_lp = sqlite3.connect('login_password.db')  #Создаем базу данных login_password

cursor_db = db_lp.cursor()  #Объект класса Cursor для выполнения SQL-запросов

#SQL-запрос для создания таблицы password в базе данных 
sql_create = '''CREATE TABLE passwords(  
login TEXT PRIMARY KEY, 
password TEXT NOT NULL);''' 

cursor_db.execute(sql_create)  #Выполняем запрос sql_create 
db_lp.commit()  #Подтверждаем изменения

#Закрываем Cursor и базу данных 
cursor_db.close()   
db_lp.close()

Добавление поясняющих заметок в каждой строке кода делает процесс создания базы данных более прозрачным и понятным. Аналогично это работает и в любых других проектах. 

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

Программисты часто сталкиваются с понятием «закомментированный код» – это код (не текст) или его фрагмент, перед которым стоит символ #. Соответственно, программа игнорирует его при выполнении. 

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

Закомментированный код полезен в случаях, когда нужно сохранить текущие версии проекта и параллельно протестировать альтернативные решения. Это позволяет гибко работать с разными идеями, возвращаясь к предыдущим версиям при необходимости. В большинстве сред разработки (IDE) можно выделить сразу несколько строк и закомментировать их одновременно.

Например, закомментирование нескольких строк может выглядеть так:

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

Что такое PEP?

PEP (Python Enhancement Proposal) – это концепция, предназначенная для организации работы с языком Python и его улучшения. PEP представляет собой документацию, в которой содержатся официальные положения, инструкции и рекомендации для разработчиков. Эти документы служат руководством по стандартам и лучшим практиками, которых следует придерживаться при написании и поддержке кода на Python.

PEP охватывает широкий спектр предложений и стандартов, в том числе:

• Развитие языка Python – направления и стратегии для расширения функциональности Python.
• Изменение и внедрение функций – рекомендации по добавлению новых возможностей и оптимизации существующих.
• Стандарты для написания кода – правила оформления кода, которые делают его более читаемым и понятным.
• Исполнение требований и их применение – порядок выполнения стандартов и их использование в реальных проектах.

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

Docstring в Python

Docstring в Python – это строковый литерал, который предназначен для документирования кода. Он часто используется для добавления пояснений к модулям, функциям, методам и классам. В отличие от обычного комментария, docstring имеет более формальный статус и служит удобным способом документирования, поскольку доступен в качестве атрибута __doc__ у объектов.

Для создания docstring используют тройные кавычки ("""), в которые помещается текст. Python игнорирует этот текст при выполнении кода, но сохраняет его как документирующий атрибут, доступный в __doc__.

Пример использования docstring

В примере ниже docstring используется для класса и метода:

class Dog:
    """
    Это класс собаки.
    """

    def bark(self):
        """
        Собака лает из метода!
        """
        return True


animal = Dog()
print(animal.__doc__)
print(animal.bark.__doc__)

Результат будет выглядеть следующим образом:

Это класс для представления собаки.
Метод, который заставляет собаку лаять.

Однострочные и многострочные docstring

Docstring можно использовать для кратких однострочных комментариев и более сложных многострочных описаний. В Python использование тройных кавычек (""") считается стандартом для docstring, но для однострочных описаний иногда применяют апострофы (''').

Руководство по документированию Python (PEP 257) определяет такие правила для написания docstring:

• Модули – краткое перечисление ключевых объектов с однострочными пояснениями.
• Функции и методы – описание поведения, перечень аргументов, сведений об исключениях и ограничениях.
• Классы – информация о методах, переменных и общем поведении класса.
• Скрипты – общая функциональность, описание параметров, среды, задействованных файлов.

Пример однострочного docstring:

def add(a, b):
    """Возвращает сумму двух чисел."""
    return a + b

Рекомендации PEP 257 для docstring

PEP 257 предлагает ряд рекомендаций для структурирования и стилистики docstring в Python. Эти рекомендации создают единое руководство по стилю документации, делая ее более понятной и удобной:

• Добавляйте пустую строку после docstring – это визуально отделяет документацию от кода, что улучшает их читаемость.
• Функции и методы нужно описывать с указанием назначения, параметров и возвращаемых значений – это облегчает понимание их работы, входных данных и результата.
• Документируйте ключевые объекты и их назначение в модулях и классах – это позволяет быстро получить представление об их содержимом и структуре.
• Если один класс наследует функциональность другого, указывайте в его docstring информацию о родительском классе и изменениях, которые добавляет дочерний класс. Это помогает лучше понять изменения и специфику нового класса.

Следование этим руководствам позволяет поддерживать стиль документации на высоком уровне, упрощая ее чтение и восприятие.

Полезные инструменты для написания кода в Python

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

К основным инструментам можно отнести следующие:

• Pycodestyle – проверяет соответствие кода стандартам PEP 8, помогает поддерживать его стиль и форматирование в едином формате.
• Pylint и PyFlakes – анализируют код на наличие ошибок, потенциальных проблем и предупреждают о нарушениях стиля. Эти инструменты помогают улучшить качество кода, автоматически выявляя участки, которые требуют внимания.
• Black – автоматический форматтер кода, который форматирует его в соответствии с PEP 8. Он особенно полезен при работе в команде, так как обеспечивает единый стиль кодирования.
• Doxygen и PyDoc – инструменты для автоматического создания документации на основе docstring, что упрощает поддержание актуальности документации кода.
• PyCharm – интегрированная среда разработки (IDE), которая включает в себя средства для выявления проблем, найденных другими инструментами, а также предоставляет удобные функции для редактирования, отладки и управления проектами на Python.

Наиболее популярными инструментами для анализа кода являются Pylint и PyFlakes, которые помогают поддерживать высокое качество кода. Black часто используется в командной работе для унификации формата кода, что делает взаимодействие между разработчиками более удобным.

Выбор подходящих инструментов и IDE, таких как PyCharm, помогает настроить комфортную и эффективную среду для разработки на Python.

Заключение

Комментарии в Python – это неотъемлемая часть профессионального программирования, которая способствует ясности кода и удобству поддержки проекта. Использование стандартов PEP в сочетании с современными инструментами позволяет обеспечить единый стиль и высокое качество кода. Такой подход позволяет поддерживать высокие стандарты качества, минимизировать ошибки и улучшать взаимодействие между разработчиками.