Добавление Комментариев в Python

Введение

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

Понимание Назначения Комментариев

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

Давайте начнем с простого скрипта без каких-либо комментариев. В WebIDE найдите файл purpose.py в проводнике файлов на левой панели и откройте его.

Добавьте следующий код в файл purpose.py:

x = 10
y = 20
z = x + y
print(z)

Сохраните файл, нажав Ctrl + S.

Чтобы запустить скрипт, откройте интегрированный терминал в WebIDE, перейдя в верхнем меню и выбрав Terminal -> New Terminal. Терминал откроется в нижней части экрана, и путь по умолчанию будет ~/project.

Выполните скрипт, запустив следующую команду в терминале:

python purpose.py

Вы увидите результат вычисления:

30

Этот скрипт прост, но в более крупной программе может быть не сразу ясно, что представляют собой x, y и z. На следующем шаге мы добавим комментарии, чтобы сделать этот код более понятным.

Использование Однострочных Комментариев

Однострочные комментарии используются для коротких пояснительных заметок. В Python однострочный комментарий начинается с символа решетки (#). Интерпретатор игнорирует все, что следует за символом # в этой строке. Эти комментарии могут располагаться на отдельной строке для описания кода ниже или в той же строке, что и оператор, для его пояснения.

Давайте изменим файл purpose.py, чтобы включить в него однострочные комментарии. Откройте purpose.py в редакторе и обновите его содержимое следующим образом:

## This script calculates the sum of two numbers

x = 10  ## Assign the integer 10 to variable x
y = 20  ## Assign the integer 20 to variable y
z = x + y  ## Calculate the sum of x and y
print(z) ## Print the final result to the console

Сохраните файл (Ctrl + S) и снова запустите его из терминала:

python purpose.py

Вывод будет таким же, как и раньше:

30

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

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

Для более длинных объяснений, охватывающих несколько строк, вы можете использовать формат многострочного комментария. Хотя в Python нет специального синтаксиса для многострочных комментариев, как в некоторых других языках, для этой цели можно использовать многострочные строки (multi-line strings).

Многострочная строка создается путем заключения текста в тройные кавычки: либо """...""" (двойные), либо '''...''' (одинарные). Если эта многострочная строка не присвоена переменной, интерпретатор Python проигнорирует ее, фактически превращая в комментарий. Это распространенная конвенция для написания блочных комментариев или документации функций (docstrings).

Найдите и откройте файл multiline.py в WebIDE. Добавьте следующий код:

"""
This is a multi-line comment using triple double quotes.
This script demonstrates how to write comments that span
several lines to provide more detailed explanations.
"""

message = "Hello, Python learners!"
print(message)

Сохраните файл и запустите его из терминала:

python multiline.py

Вы увидите следующий вывод:

Hello, Python learners!

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

Использование Комментариев Объявления

Python также поддерживает специальные комментарии, известные как объявляющие комментарии (declaration comments). Они обрабатываются интерпретатором или операционной системой для настройки того, как выполняется скрипт. Два распространенных примера — это shebang и объявление кодировки.

1. Shebang (#!): Строка shebang — это самая первая строка в скрипте. Она указывает операционной системе, подобной Unix, какой интерпретатор использовать для выполнения файла. Для скрипта Python 3 это обычно #!/usr/bin/python3. Это позволяет запускать скрипт как автономный исполняемый файл.

2. Объявление Кодировки (Encoding Declaration): Этот комментарий сообщает интерпретатору Python, какую кодировку символов использовать для исходного файла. Это важно, если ваш код содержит символы, отличные от ASCII. Стандартное объявление для UTF-8: ## -*- coding: utf-8 -*-. Оно должно располагаться на первой или второй строке файла.

Давайте создадим скрипт, использующий оба типа. Откройте файл declaration.py в редакторе и добавьте следующий код:

#!/usr/bin/python3
## -*- coding: utf-8 -*-

## This script demonstrates declaration comments and non-ASCII characters.
print("Hello, World!")
print("你好，世界！") ## A greeting in Chinese

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

chmod +x declaration.py

Теперь вы можете выполнить скрипт напрямую, не вводя сначала python:

./declaration.py

Вывод корректно отобразит обе строки текста, включая китайские иероглифы:

Hello, World!
你好, 世界!

Строка shebang позволила системе найти и использовать интерпретатор Python 3, а объявление кодировки гарантировало корректную обработку символов, отличных от ASCII.

Резюме

В этой лабораторной работе вы узнали, как добавлять комментарии в ваш код на Python. Вы практиковались в использовании однострочных комментариев с помощью # для кратких заметок, многострочных комментариев с помощью """...""" для более длинных описаний и специальных объявляющих комментариев, таких как shebang и объявление кодировки, для настройки выполнения скрипта. Эффективно комментируя свой код, вы делаете его более читаемым, удобным для сопровождения и более понятным для других (и для вашего будущего "я").