Курс Модуль 1: Python Core - Лекция: Комментарии в коде

5.1 Как писать комментарии

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

Однострочные комментарии:

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

# Это однострочный комментарий
print("Hello, World!") # Пояснение к действию функции

Многострочные комментарии:

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

# Это пример многострочного комментария
# Каждая строка начинается с символа #

или:

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

5.2 Зачем писать комментарии

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

Документирующие строки (docstrings):

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

Пример:

def add(a, b):
"""
    Функция для сложения двух чисел.
    :param a: первое слагаемое
    :param b: второе слагаемое
    :return: сумма a и b
    """
    return a + b

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

Пример 1


 

            # Я бы объяснил, что здесь происходит, но даже мне уже не понятно.

Пример 2


 

    # Если это не работает, то виноват кто-то другой.

Пример 3


 

    # Пришел, увидел, исправил... и сломал.

Пример 4


 

    # Когда я написал это, только я и Бог знали, как это работает. 
    # Теперь знает только Бог.

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

5.3 Быстро закомментировать код

В PyCharm вы можете быстро закомментировать или раскомментировать код, используя горячие клавиши. Для этого выделите строки кода, которые хотите изменить, и нажмите Ctrl + / на Windows (или Cmd + / на macOS). Эта комбинация клавиш добавляет или убирает символ комментария на каждой выделенной строке, делая процесс быстрым и эффективным.