В этом модуле мы изучим важнейшие элементы документирования кода в Python - комментарии и docstrings. Вы узнаете, как правильно оставлять пояснения в коде, чтобы он был понятен не только вам, но и другим разработчикам. Научитесь использовать однострочные и многострочные комментарии, познакомитесь с концепцией документирующих строк (docstrings) для функций, классов и модулей. Также рассмотрим стандарты оформления документации PEP 257 и узнаем, как Python обрабатывает комментарии при выполнении программы. Правильное документирование - это признак профессионального подхода к программированию, который значительно упрощает поддержку и развитие проектов.
- Модуль 1: Основы синтаксиса Python
- Первая программа и print().
- Комментарии и документация.
- Отступы и блоки кода.
- Точка с запятой и перенос строк.
- Модуль 2: Переменные и типы данных
- Модуль 3: Операторы
- Арифметические операторы (+, -, *, /).
- Целочисленное деление и остаток (// и %).
- Возведение в степень (**).
- Операторы сравнения.
- Логические операторы (and, or, not).
- Операторы присваивания (=, +=, -=).
- Операторы принадлежности (in, not in).
- Операторы идентичности (is, is not).
- Битовые операторы.
- Тернарный оператор.
- Модуль 4: Ввод и вывод данных
- Модуль 5: Условные конструкции
- Модуль 6: Циклы
- Модуль 7: Строки
- Модуль 8: Списки
- Модуль 9: Кортежи
- Модуль 10: Словари
- Модуль 11: Множества
- Модуль 12: Функции
- Модуль 13: Встроенные функции
- Модуль 14: Работа с файлами
- Модуль 15: Обработка исключений
- Модуль 16: Модули и пакеты
- Модуль 17: ООП - Основы
- Модуль 18: ООП - Продвинутый уровень
- Модуль 19: Декораторы
- Модуль 20: Генераторы и итераторы
- Модуль 21: Регулярные выражения
- Модуль 22: Дата и время
- Модуль 23: Математические операции
- Модуль 24: Работа с сетью
- Модуль 25: Асинхронное программирование
- Модуль 26: Многопоточность
- Модуль 27: Тестирование
- Модуль 28: Базы данных
- Модуль 29: Алгоритмы и структуры данных
- Модуль 30: Продвинутые возможности
Синтаксис однострочных комментариев
Добавьте правильный символ для создания комментариев в Python. Все комментарии в Python начинаются с одного и того же специального символа.
input1S Объявляем переменную с именем
name = "Alice"
input2S Выводим приветствие
print(f"Hello, {name}!")
age = 25 input3S Сохраняем возрастИсправьте синтаксис комментариев
В этом коде используется неправильный синтаксис комментариев из других языков программирования. Замените их на правильный синтаксис Python.
// Функция для расчета площади прямоугольникаdef calculate_area(length, width): """Вычисляет площадь прямоугольника""" return length * width /* Тестируем функцию */result = calculate_area(5, 3)print(result) # Выводим результатОформите docstring для функции
Создайте правильно оформленную документирующую строку (docstring) для функции сложения двух чисел. Используйте тройные кавычки и правильный оператор.
def add_numbers(a, b):
input1SСкладывает два числа и возвращает результатinput2S
return a input3S b
# Тест функции
print(add_numbers(10, 20)) # Должно вывести 30Влияние комментариев на выполнение кода
Определите, что выведет этот код. Обратите внимание на то, как Python обрабатывает комментарии при выполнении программы.
x = 10 # x = 20
y = 5
# z = x + y
z = x - y # Вычисляем разность
print(z) # print(x + y)Структура Python модуля с документацией
Соберите правильно структурированный Python модуль. Он должен начинаться с docstring модуля, затем импорты, потом функция с её docstring. Две строки являются лишними - они используют неправильный синтаксис.
"""Модуль для математических вычислений."""import mathdef square(n): """Возвращает квадрат числа.""" return n ** 2# Тестируем функциюprint(square(5))// Это неправильный комментарий/* Многострочный комментарий */Классификация элементов документации
Распределите элементы по трём категориям согласно их роли в Python. Обратите внимание на синтаксис каждого элемента.
Атрибут __doc__ функции
Определите, что выведет обращение к атрибуту __doc__ функции. Введите точный текст, который будет выведен (без кавычек).
def calculate(x, y):
"""Выполняет вычисление"""
return x + y
print(calculate.__doc__)Многострочные блоки текста в Python
Дополните код, используя правильный синтаксис для многострочных текстовых блоков и docstring класса. В Python для этого используются тройные кавычки.
input1S
Этот блок текста
занимает несколько строк
и будет проигнорирован Python
input2S
class MyClass:
input3SКласс для демонстрацииinput4S
def __init__(self):
self.value = 0Структура docstring в стиле Google
Расставьте строки в правильном порядке для создания функции с документацией в стиле Google. Функция должна вычислять факториал числа.
def factorial(n): """Вычисляет факториал числа. Args: n: Целое неотрицательное число. Returns: Факториал числа n. """ if n == 0: return 1 return n * factorial(n - 1)Исправьте отступы в документации класса
В коде есть проблемы с отступами docstring и форматированием инлайн-комментария. Исправьте ошибки согласно стандартам PEP 8.
class Calculator:"""Класс для вычислений.""" def add(self, a, b): """Складывает два числа.""" result = a + b#сложение return resultМногострочные строки как выражения
Проанализируйте код и определите, что будет выведено. Обратите внимание на поведение многострочных строк, которые не являются docstring.
def test():
"""Это docstring функции"""
'''
Это многострочная строка,
но она не docstring и не присвоена переменной,
поэтому Python её проигнорирует
'''
return "Результат"
print(test())
print(test.__doc__)