Чистый код на Python: комментарии, докстринги и PEP 8

Начальный15 min4 упр.90 XP

Этот урок переведён с английского оригинала.Read in English Leer en español Сообщить об ошибке в переводе

Перед началом

Преобразование типов в Python: int(), float(), str(), bool()

0/4 упр.

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

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

В этом уроке вы научитесь писать на Python так, чтобы другим людям (и вам самим в будущем) было приятно читать ваш код. Мы разберём комментарии, строки документации, правила именования и PEP 8, официальное руководство по стилю Python.

Почему чистый код так важен?

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

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

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

Неряшливый и чистый код: результат один, впечатления совсем разные

# Which version would you rather read?

# Version A

x = 3.14159

y = 10

z = x * y * y

print(z)

# Version B

pi = 3.14159

radius = 10

circle_area = pi * radius * radius

print(f"Area of circle: {circle_area}")

Вывод

314.159
Area of circle: 314.159

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

Как писать хорошие комментарии в Python

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

Хороший комментарий объясняет, зачем что-то сделано, а не что делает код. Если код достаточно понятен, ответ на вопрос «что» виден при чтении.

❌ Плохие комментарии (объясняют очевидное)

# Set x to 5
x = 5

# Add 1 to x
x = x + 1

# Print x
print(x)

✓ Хорошие комментарии (объясняют «зачем»)

# Start with 5 retries (server sometimes drops first request)
retry_count = 5

# Move to next attempt
retry_count = retry_count + 1

print(retry_count)

Заметили разницу? Плохие комментарии повторяют то, что и так написано в коде. Хорошие объясняют, зачем этот код нужен, и дают контекст, которого из самого кода не узнать.

Когда стоит добавлять комментарии в код на Python?

Добавляйте комментарий, когда код делает что-то неожиданное или неочевидное. Если человек, читающий ваш код, спросит «погодите, а почему так?», значит, здесь нужен комментарий.

Комментарии, которые действительно помогают

# Good reasons to comment:

price = 9.99

tax = price * 0.0825 # Texas sales tax rate (8.25%)

# Multiply by 100 to avoid floating-point rounding errors

price_in_cents = int(price * 100)

# TODO: Replace with database lookup once API is ready

user_name = "Guest"

Вывод

(нет вывода)

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

Когда комментарии лучше не писать?

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

❌ Комментарий прикрывает непонятный код

# Calculate the final price with 20% discount
p = x - (x * 0.2)

✓ Понятному коду комментарий не нужен

discount_rate = 0.20
final_price = original_price - (original_price * discount_rate)

Что такое строки документации (docstring) в Python?

Строка документации (docstring, или докстринг) описывает, что делает функция, класс или модуль. Это особая строка в самом начале тела функции, заключённая в тройные кавычки (""").

Докстринг похож на инструкцию, которая прилагается к прибору. Чтобы понять, что делает прибор, не нужно его разбирать: достаточно прочитать инструкцию.

Функция с правильным докстрингом

def calculate_tip(bill_amount, tip_percent):

"""Calculate the tip amount for a restaurant bill.

Args:

bill_amount: The total bill in dollars.

tip_percent: The tip percentage (e.g., 20 for 20%).

Returns:

The tip amount in dollars.

"""

return bill_amount * (tip_percent / 100)

# Using the function

tip = calculate_tip(50.00, 20)

print(f"Tip: ${tip:.2f}")

# You can view any function's docstring with help()

help(calculate_tip)

Вывод

Tip: $10.00
Help on function calculate_tip in module __main__:

calculate_tip(bill_amount, tip_percent)
    Calculate the tip amount for a restaurant bill.

    Args:
        bill_amount: The total bill in dollars.
        tip_percent: The tip percentage (e.g., 20 for 20%).

    Returns:
        The tip amount in dollars.

Если вызвать help() для функции, Python покажет её докстринг. Так же свою документацию показывают и встроенные функции вроде print() и len().

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

Простой однострочный докстринг

# Simple function - one-line docstring is fine

def square(n):

"""Return the square of a number."""

return n * n

print(square(7))

print(square(12))

Вывод

49
144

Правила именования в Python: как называть переменные

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

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

Правила именования Python на практике

# snake_case - the Python way

user_name = "Alice"

total_price = 29.99

is_logged_in = True

max_retry_count = 3

# Use these in practice

print(f"User: {user_name}")

print(f"Total: ${total_price}")

print(f"Logged in: {is_logged_in}")

print(f"Max retries: {max_retry_count}")

Вывод

User: Alice
Total: $29.99
Logged in: True
Max retries: 3

Вот основные правила именования, которых придерживаются Python-разработчики:

Как называть разные сущности

# Variables and functions: snake_case

player_score = 100

def calculate_average(numbers):

"""Return the average of a list of numbers."""

return sum(numbers) / len(numbers)

# Constants: UPPER_SNAKE_CASE

MAX_SPEED = 120

PI = 3.14159

DATABASE_URL = "localhost:5432"

# Classes: PascalCase (you'll learn classes later)

# class PlayerCharacter:

# class ShoppingCart:

print(f"Player score: {player_score}")

print(f"Max speed: {MAX_SPEED}")

print(f"Pi: {PI}")

Вывод

Player score: 100
Max speed: 120
Pi: 3.14159

Как выбирать осмысленные имена переменных

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

❌ Расплывчатые или загадочные имена

x = "Alice"
n = 25
f = True
temp = 3
data = 98.6
my_list = ["math", "science"]

✓ Говорящие, осмысленные имена

student_name = "Alice"
student_age = 25
is_enrolled = True
max_attempts = 3
body_temperature = 98.6
course_list = ["math", "science"]

Однобуквенные имена вроде x, n и i вполне уместны в коротких математических формулах или крошечных циклах. Во всех остальных случаях выбирайте настоящее имя, которое объясняет назначение переменной.

Что такое PEP 8? Основы руководства по стилю Python

PEP 8 является официальным руководством по стилю Python. PEP расшифровывается как «Python Enhancement Proposal» (предложение по улучшению Python), а документ под номером 8 посвящён стилю кода. Это что-то вроде дресс-кода для Python: все следуют одним и тем же правилам, поэтому любой код на Python выглядит привычно.

Заучивать каждое правило не нужно. Вот те, что важнее всего на старте.

Как делать отступы в Python (4 пробела)

Python объединяет строки кода в блоки с помощью отступов. Стандарт: 4 пробела на каждый уровень. Никогда не смешивайте табуляцию и пробелы: выберите что-то одно (пробелы) и придерживайтесь этого.

Правильные отступы в 4 пробела

# Correct: 4 spaces for each indentation level

def greet(name):

"""Print a greeting message."""

if name:

message = f"Hello, {name}!"

print(message)

else:

print("Hello, stranger!")

greet("Alice")

greet("")

Вывод

Hello, Alice!
Hello, stranger!

Как использовать пустые строки в коде на Python

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

Пустые строки разделяют части кода

# Two blank lines before a function definition

def calculate_area(width, height):

"""Calculate the area of a rectangle."""

return width * height

def calculate_perimeter(width, height):

"""Calculate the perimeter of a rectangle."""

return 2 * (width + height)

# Use the functions

area = calculate_area(5, 3)

perimeter = calculate_perimeter(5, 3)

print(f"Area: {area}")

print(f"Perimeter: {perimeter}")

Вывод

Area: 15
Perimeter: 16

Ставьте две пустые строки до и после определений функций верхнего уровня. Внутри функции разделяйте логические части одной пустой строкой.

Как ставить пробелы вокруг операторов в Python

Ставьте по одному пробелу с каждой стороны от операторов =, +, -, == и !=. Так код гораздо легче читать с первого взгляда.

❌ Без пробелов (трудно читать)

total=price*quantity+tax
is_valid=age>=18 and name!=""
result=x**2+y**2

✓ Пробелы вокруг операторов (легко читать)

total = price * quantity + tax
is_valid = age >= 18 and name != ""
result = x**2 + y**2

Частые ошибки стиля в Python и как их исправить

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

❌ Прямое сравнение с True/False/None

if is_active == True:
    print("Active")

if result == None:
    print("No result")

✓ Как принято в Python

if is_active:
    print("Active")

if result is None:
    print("No result")

Не сравнивайте с True или False через ==. Используйте саму переменную. Для None всегда пишите is None вместо == None.

❌ Стили вперемешку

userName = "Alice"      # camelCase
total_Price = 29.99     # mixed style
def CalculateTotal():   # PascalCase for function
    pass

✓ Везде snake_case

user_name = "Alice"     # snake_case
total_price = 29.99     # snake_case
def calculate_total():   # snake_case
    pass

Выберите стиль и придерживайтесь его. В Python это snake_case для переменных и функций. Смесь стилей делает код хаотичным.

❌ Слишком много пустых строк или ни одной

def add(a, b):
    return a + b
def subtract(a, b):
    return a - b
def multiply(a, b):
    return a * b

✓ Две пустые строки между функциями

def add(a, b):
    return a + b


def subtract(a, b):
    return a - b


def multiply(a, b):
    return a * b

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

Запоминать каждое правило PEP 8 не обязательно. Специальные инструменты, линтеры, умеют автоматически находить в коде проблемы со стилем. Линтер похож на проверку орфографии, только для стиля кода.

Вот самые популярные линтеры для Python:

`flake8`: ищет нарушения PEP 8 и типичные ошибки. Отлично подходит новичкам.

`pylint`: проверяет тщательнее и вдобавок подсказывает, как улучшить качество кода.

`ruff`: новичок в этой компании. Работает очень быстро и заменяет сразу несколько инструментов.

`black`: автоформатер. Он не только предупреждает, но и сам исправляет стиль.

Большинство редакторов кода (например, VS Code) умеют запускать линтеры в фоне и подчёркивать проблемы со стилем прямо во время набора. Получается, будто рядом с вами сидит личный тренер по стилю.

Практические упражнения

Пора практиковаться! Эти упражнения помогут выработать привычку писать чистый и читаемый код на Python.

Упражнение 1: добавьте комментарии и докстринг

Напишите код

Напишите функцию celsius_to_fahrenheit, которая принимает температуру в градусах Цельсия и возвращает значение в градусах Фаренгейта.

Формула: fahrenheit = celsius * 9/5 + 32

В функции обязательно должны быть:

докстринг, описывающий, что она делает;

комментарий, поясняющий формулу.

Затем выведите результат перевода 100 градусов Цельсия. Вывод должен быть таким:

212.0

# Write your function with a docstring and comment

Упражнение 2: исправьте неудачные имена переменных

Исправьте ошибку

Этот код работает, но имена переменных в нём ужасные! Никто не догадается, что означают x, y, z и a.

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

Weekly pay: $450.0
With overtime: $562.5

x = 15.0

y = 30

z = x * y

a = 5

b = x * 1.5 * a

print(f"Weekly pay: ${z}")

print(f"With overtime: ${z + b}")

Упражнение 3: перепишите неряшливый код по PEP 8

Напишите код

Код ниже написан неряшливо. Перепишите его по правилам PEP 8:

def calcArea(W,H):
  result=W*H
  return result
def calcPerimeter(W,H):
  result=2*(W+H)
  return result
w=8
h=5
print(f"Area: {calcArea(w,h)}")
print(f"Perimeter: {calcPerimeter(w,h)}")

Что нужно исправить:

имена функций переведите в стиль snake_case;

сделайте отступы в 4 пробела;

добавьте пробелы вокруг операторов и после запятых;

поставьте две пустые строки между определениями функций;

дайте переменным осмысленные имена.

Вывод должен быть таким:

Area: 40
Perimeter: 26

# Rewrite the messy code below following PEP 8 rules

Упражнение 4: рефакторинг неряшливого кода

Улучшите код

Эта функция работает, но написана неряшливо. Проведите рефакторинг, чтобы код стал чистым и профессиональным:

def d(p,r):
  a=p*r/100
  t=p-a
  return t
print(d(200,15))

В вашей версии нужно:

дать функции осмысленное имя (она вычисляет цену со скидкой);

дать параметрам говорящие имена;

добавить докстринг, объясняющий, что делает функция;

соблюсти отступы и пробелы по PEP 8 (отступ в 4 пробела, пробелы вокруг операторов);

поставить две пустые строки перед вызовом функции.

Вывод должен быть таким:

170.0

# Refactor the messy code into clean, professional Python

Итоги: что вы узнали о чистом коде на Python

Теперь вы знаете привычки, которые отличают код новичка от кода профессионала. Краткая шпаргалка:

Понятие	Главное правило	Пример
Комментарии (`#`)	Объясняйте зачем, а не что	`# Texas tax rate (8.25%)`
Докстринги (`"""`)	Описывают, что делает функция	`"""Convert Celsius to Fahrenheit."""`
Имена переменных	Говорящие, `snake_case`	`total_price`, `is_valid`
Константы	`UPPER_SNAKE_CASE`	`MAX_SPEED = 120`
Отступы	Всегда 4 пробела	`def greet():`, затем 4 пробела
Пустые строки	2 между функциями	Разделяют логические части
Операторы	Пробелы вокруг `=`, `+` и т. д.	`x = a + b`
PEP 8	Официальное руководство по стилю Python	Единообразие превыше всего

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

Что дальше?

Вы прошли раздел «Основы Python»! Теперь у вас прочный фундамент. Дальше вас ждут управляющие конструкции: вы научите программы принимать решения с помощью инструкций if и повторять действия с помощью циклов.

Почему чистый код так важен?

Как писать хорошие комментарии в Python

Когда стоит добавлять комментарии в код на Python?

Когда комментарии лучше не писать?

Что такое строки документации (docstring) в Python?

Правила именования в Python: как называть переменные

Как выбирать осмысленные имена переменных

Что такое PEP 8? Основы руководства по стилю Python

Как делать отступы в Python (4 пробела)

Как использовать пустые строки в коде на Python

Как ставить пробелы вокруг операторов в Python

Частые ошибки стиля в Python и как их исправить

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

Практические упражнения

Итоги: что вы узнали о чистом коде на Python

Что дальше?

Похожие уроки