Основы чистого кода, рефакторинга в Python. PEP8.

Что такое чистый код?

Чистый код — это код, который легко читается, понимается и поддерживается.

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

Почему чистый код важен для разработчика и команды?

1. Читаемость:
   • Облегчает понимание кода другими разработчиками, включая вас в будущем.
   • Уменьшает вероятность ошибок при сопровождении кода.
2. Сопровождаемость:
   • Упрощает процесс поиска и устранения ошибок.
   • Облегчает внесение изменений и добавление новых функциональностей.
3. Коллективная работа:
   • Позволяет команде эффективно сотрудничать над проектом.
   • Уменьшает время, необходимое для интеграции изменений от разных разработчиков.
4. Снижение технического долга:
   • Уменьшает вероятность появления технического долга, так как чистый код проще поддерживать.

Пример плохого кода и результат его оптимизации

Плохой код:

def calc(a, b):
    c = a + b
    d = c * 2
    print("Result is: " + str(d))
    return d

Этот код не соответствует принципам чистого кода:

• Неинформативные имена переменных (a, b, c, d).
• Использование магических чисел.
• Комбинация вычислений и вывода результата внутри функции.

Оптимизированный код:

def calculate_result(value1, value2):
    sum_result = value1 + value2
    multiplied_result = sum_result * 2
    return multiplied_result

# Вывод результата за пределы функции
result = calculate_result(3, 5)
print(f"Result is: {result}")

В оптимизированном коде:

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

Что такое «технический долг» ?

Технический долг (technical debt) — это метафора, используемая в разработке программного обеспечения для описания ситуации, когда в процессе разработки были сделаны выборы или приняты решения, которые, хоть и позволили достичь цели быстрее, но при этом создали долг, который в будущем придется погасить. На сленге русскоязычных программистов еще есть термин «костыль«.

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

Основные характеристики технического долга:

1. Быстрое решение проблемы: Технический долг возникает, когда команда выбирает быстрое решение проблемы, часто за счет качества кода или архитектурных решений.
2. Необходимость в будущем улучшении: Как и с финансовым долгом, технический долг «погашается» путем проведения дополнительной работы, например, рефакторинга кода или оптимизации архитектуры.
3. Ухудшение читаемости и поддерживаемости: Последствия технического долга могут проявляться в форме менее читаемого, менее структурированного кода, что затрудняет его понимание и поддержание.

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

Что такое рефакторинг кода?

Рефакторинг кода — это процесс изменения внутренней структуры программы с целью улучшения её читаемости, поддерживаемости и/или производительности, при этом не изменяя её внешнего поведения. Термин «рефакторинг» введен Мартином Фаулером (Martin Fowler) и его коллегами.

Основные причины для проведения рефакторинга включают:

1. Улучшение читаемости: Понятный и легко читаемый код облегчает его сопровождение и совместное использование в команде.
2. Улучшение поддерживаемости: Чем более модульный и структурированный код, тем проще внесение изменений и добавление новой функциональности.
3. Устранение дублирования: Рефакторинг может помочь избежать повторения кода, что улучшает его поддерживаемость и уменьшает вероятность ошибок.
4. Повышение производительности: Оптимизация алгоритмов или структур данных может улучшить производительность программы.
5. Соблюдение стандартов кодирования: Рефакторинг может включать в себя выравнивание кода согласно стандартам кодирования, таким как PEP8 в случае Python.

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

Что такое PEP8?

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

Некоторые ключевые принципы PEP8 включают:

1. Отступы: Используйте 4 пробела для отступов. Не рекомендуется использовать табуляцию.
2. Максимальная длина строки: Соблюдайте максимальную длину строки в 79 символов (или 72, если включен автоматический перенос строки).
3. Пустые строки: Используйте пустые строки для организации кода логически, но избегайте избыточного использования.
4. Именование переменных и функций: Используйте соглашение snake_case для именования переменных и функций. Избегайте использования «CamelCase» в обычных переменных.
5. Импорты: Импортируйте модули по одному на строку, избегайте использования «wildcard» (*) в импортах.
6. Пробелы вокруг операторов и после запятых: Рекомендуется использование пробелов вокруг операторов и после запятых, чтобы улучшить читаемость кода.

Пример соблюдения стандартов PEP8:

def calculate_total_price(item_price, quantity):
    tax_rate = 0.1
    total_price = item_price * quantity * (1 + tax_rate)
    return total_price

items = [10, 5, 8, 12, 3]
for item in items:
    total = calculate_total_price(item, 2)
    print(f'Total price for {item} items: {total}')

Читабельность (понятность) и поддерживаемость кода

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

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

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

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

Читаемость и поддерживаемость кода являются критически важными аспектами в разработке ПО, поскольку:

1. Облегчение сотрудничества: Читабельный и поддерживаемый код упрощает командную работу, поскольку другие разработчики (включая вас в будущем) смогут быстро понять код и внести необходимые изменения.
2. Сокращение времени на разработку и поддержку: Код, который легко читается и поддерживается, снижает время, необходимое для добавления новых функций, исправления ошибок и общего сопровождения программы.
3. Уменьшение риска ошибок: Читаемый код с меньшей вероятностью содержит ошибки, так как разработчики могут лучше понимать его структуру и намерения.
4. Улучшение масштабируемости: Поддерживаемый код облегчает добавление нового функционала и изменение программы в соответствии с растущими требованиями.

Все эти аспекты способствуют повышению качества программного обеспечения и его устойчивости в долгосрочной перспективе.

Основы чистого кода

Понятность кода

1. Именование переменных и функций

Почему важно:

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

Советы:

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

Пример:

# Плохо
a = 5
b = 10

# Хорошо
total_items = 5
maximum_quantity = 10

2. Комментарии и их использование

Почему важно:

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

Советы:

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

Пример:

# Плохо: Излишне детализированный комментарий
result = calculate_total_price(item, 2)  # Рассчитывает общую стоимость товара, умножая цену товара на количество товара и применяется налоговая ставка

# Хорошо: Комментарий объясняет сложную логику
result = calculate_total_price(item, 2)  # Умножаем цену товара на количество и добавляем налог

3. Избегание магических чисел

Почему важно:

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

Советы:

• Используйте именованные константы для магических чисел.
• Если число имеет какой-то смысл, предоставьте ему имя.
• Объявляйте константы в начале файла или модуля.

Пример:

# Плохо
total_price = item_price * 2.5  # 2.5 - магическое число, неясно, что оно представляет

# Хорошо
TAX_RATE = 2.5
total_price = item_price * TAX_RATE  # Использование именованной константы

Задания на тренировку

Задание 1: Исправление имен переменных и комментариев. Исправьте код ниже, для улучшения его наглядности (читабельности)

a = 5
b = 3

# Рассчитываем результат и выводим его на экран
result = a * b
print(result)

Структура кода

1. Отступы и структура блоков кода

Почему важно:

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

Советы:

• Используйте 4 пробела для отступов (стандарт PEP8 для Python).
• Выравнивайте блоки кода, чтобы они визуально отображали свою структуру.
• Поддерживайте последовательность отступов в пределах одного проекта.

Пример:

# Плохо
if condition:
result = calculate_total_price(item, 2)
print(f'Total price for {item} items: {result}')

# Хорошо
if condition:
    result = calculate_total_price(item, 2)
    print(f'Total price for {item} items: {result}')

2. Длина строк и оформление длинных выражений

Почему важно:

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

Советы:

• Соблюдайте ограничение длины строки (стандарт PEP8 рекомендует 79 символов).
• Если выражение слишком длинное, используйте скобки или перенос строки для улучшения читаемости.

Пример:

# Плохо: Длинная строка
result = calculate_total_price(item, 2) + calculate_shipping_cost(item) + calculate_discount(item) + calculate_tax(item)

# Хорошо: Разбитие на несколько строк
result = (calculate_total_price(item, 2) +
          calculate_shipping_cost(item) +
          calculate_discount(item) +
          calculate_tax(item))

Задания для тренировки

Задание 2: Улучшение структуры и отступов. Исправьте код ниже

def process_data(data):
    if not data:
    return None
result = perform_calculations(data)
if result:
print("Calculation successful:", result)
else:
print("Calculation failed.")
return result

Задание 3: Избегание «магических» чисел. Исправьте код ниже.

def complex_calculation(x, y):
    if x * y > 100:
        return "High"
    elif x * y > 50:
        return "Medium"
    else:
        return "Low"

result = complex_calculation(8, 7)
print(result)

Задание 4:  Длинные строки. Исправьте код ниже

result = calculate_total_price(item, 2) + calculate_shipping_cost(item) + calculate_discount(item) + calculate_tax(item)

Чистый код в функциях

Принцип единственной ответственности (Single Responsibility Principle)

Почему важен:

Принцип единственной ответственности (S in SOLID) предполагает, что функция (или класс) должна иметь только одну причину для изменения. Это означает, что функция должна выполнять только одну задачу или иметь только одну обязанность.

Советы:

• Разделяйте функции на более мелкие, каждая из которых отвечает за конкретную задачу.
• Если функция выполняет несколько задач, рассмотрите возможность разделения её на несколько более простых функций.

Пример:

# Плохо: Функция выполняет сразу две задачи
def process_data_and_print(data):
    processed_data = process_data(data)
    print_data(processed_data)

# Хорошо: Отдельные функции для обработки и вывода данных
def process_data(data):
    # обработка данных
    return processed_data

def print_processed_data(processed_data):
    # вывод обработанных данных
    print(processed_data)

2. Избегание длинных списков параметров

Почему важно:

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

Советы:

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

Пример:

# Плохо: Слишком много параметров
def create_user(name, age, email, address, phone):
    # создание пользователя

# Хорошо: Использование объекта пользователя
class User:
    def __init__(self, name, age, email, address, phone):
        self.name = name
        self.age = age
        self.email = email
        self.address = address
        self.phone = phone

def create_user(user):
    # создание пользователя

Стандарт PEP8 в Python

PEP8 (Python Enhancement Proposal — это руководство по стилю кодирования для языка программирования Python.

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

1. Единообразие в сообществе: PEP8 предоставляет общепринятые стандарты для форматирования кода на языке Python. Это способствует единообразию в сообществе разработчиков, что делает код более предсказуемым и понятным для широкого круга людей.
2. Читаемость кода: Стандарты PEP8 направлены на улучшение читаемости кода. Читабельный код легче поддерживать, и он снижает вероятность ошибок, так как разработчики могут быстро понимать его структуру и намерения.
3. Снижение объема дискуссий: Следование стандартам PEP8 позволяет избежать бесконечных дебатов в команде по поводу стиля кодирования. Это снижает время, затрачиваемое на обсуждение форматирования и позволяет сосредоточиться на более важных аспектах разработки.
4. Инструменты статического анализа кода: Многие инструменты статического анализа кода поддерживают стандарты PEP8. Это позволяет автоматически проверять соответствие кода стандартам и выделять потенциальные проблемы.
5. Облегчение интеграции кода: Когда разработчики соблюдают стандарты PEP8, интеграция и совместная работа кода становится более гладкой. Отсутствие несоответствий стандартам упрощает обзор кода и уменьшает возможность конфликтов при слиянии изменений.
6. Продвижение лучших практик: PEP8 включает в себя не только стилистические рекомендации, но и лучшие практики, например, по организации импортов, обработке исключений и др. Следование этим рекомендациям помогает писать более эффективный и безопасный код.

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

Основные требования PEP8

1. Отступы. Требование: Используйте 4 пробела для отступов, а не табуляцию.
2. Максимальная длина строки. Требование: Соблюдайте максимальную длину строки в 79 символов.
3. Пробелы вокруг операторов и после запятых. Требование: Используйте пробелы вокруг операторов и после запятых.
4. Именование переменных и функций. Требование: Используйте snake_case для именования переменных и функций.
5. Пустые строки. Требование: Используйте пустые строки для организации кода логически.
6. Импорты. Требование: Импортируйте модули по одному на строку.

# Отступы
# Плохо: Использование табуляции
def bad_function():
   	print("This is bad!")

# Хорошо: Использование 4 пробелов
def good_function():
    print("This is good!")


# Максимальная длина строки
# Плохо: Длинная строка
long_string = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."

# Хорошо: Разбитие на несколько строк
long_string = ("Lorem ipsum dolor sit amet, consectetur adipiscing elit, "
               "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.")


# Пробелы вокруг операторов и после запятых
# Плохо: Отсутствие пробелов
result=a+b

# Хорошо: Использование пробелов
result = a + b


# Именование переменных и функций
# Плохо: CamelCase
def BadFunctionName():
    return "Bad function name"

# Хорошо: snake_case
def good_function_name():
    return "Good function name"


# Пустые строки
# Плохо: Отсутствие пустых строк
def bad_function():
    result = calculate(a, b)
    print(result)
    return result

# Хорошо: Использование пустых строк
def good_function():
    result = calculate(a, b)

    print(result)
    return result


# Импорты
# Плохо: Импорт нескольких модулей в одной строке
import module1, module2, module3

# Хорошо: Каждый модуль на отдельной строке
import module1
import module2
import module3

Задание для проверки

Задание 5. Исправь код.

# Неправильный код с нарушениями PEP8

def wrong_function(data,flag):
    result=process_data(data,flag)
    if flag=='option1':
      print(result)
      return result
    else:
        print( result ) # лишние пробелы перед и после скобок
        return  result
# Длинные строки должны были быть разбиты, но я этого не сделал, добавил множество пробелов вокруг операторов
def calculate_total_price (item,quantity, discount_factor=0.1):total_price=item['price']*quantity-calculate_discount(item,discount_factor)+calculate_tax(item)

class ShoppingCart: # имена классов также должны следовать PEP8, но я не придерживаюсь этого
  def __init__(self,cart_items): self.cart_items=cart_items
  def add_item (self, item): self.cart_items.append(item)
  def remove_item (self, item):self.cart_items.remove(item)

# Пустые строки отсутствуют, что нарушает PEP8

import math,sys; print("This is a multiline import"); print(math.sqrt(25))

print ( "This line has leading and trailing whitespaces" ) # Нарушение PEP8 - лишние пробелы в начале и конце строки

Рефакторинг кода.

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

Основные принципы рефакторинга включают в себя:

1. Сохранение внешнего поведения: В ходе рефакторинга важно сохранять текущее внешнее поведение программы. Изменения внутренней структуры кода не должны приводить к изменению того, как программа взаимодействует с внешним миром.
2. Множество мелких изменений: Рефакторинг обычно предполагает множество мелких изменений в коде. Одно изменение может касаться переименования переменной, другое — выделения блока кода в отдельную функцию.
3. Поддержание работоспособности: Весь процесс рефакторинга должен проводиться так, чтобы в любой момент код оставался работоспособным. Это обеспечивается совмещением рефакторинга с тестированием.
4. Систематический подход: Рефакторинг не должен быть случайным процессом. Он должен проводиться систематически, учитывая определенные практики и принципы.

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

Примеры рефакторинга

Пример 1: Выделение повторяющегося кода в функции

Исходный код:

def calculate_area_of_circle(radius):
    area = 3.14 * radius * radius
    print(f"The area of the circle is: {area}")

def calculate_area_of_square(side):
    area = side * side
    print(f"The area of the square is: {area}")

# Повторяющийся код
calculate_area_of_circle(5)
calculate_area_of_square(4)
calculate_area_of_circle(8)

Рефакторинг:

def calculate_area_of_circle(radius):
    area = 3.14 * radius * radius
    return area

def calculate_area_of_square(side):
    area = side * side
    return area

def print_area(shape, area):
    print(f"The area of the {shape} is: {area}")

# Использование выделенных функций
circle_area_1 = calculate_area_of_circle(5)
square_area_1 = calculate_area_of_square(4)
circle_area_2 = calculate_area_of_circle(8)

print_area("circle", circle_area_1)
print_area("square", square_area_1)
print_area("circle", circle_area_2)

Пример 2: Разбиение сложных функций на более простые

Исходный код:

def process_data(data):
    # Сложные операции по обработке данных
    cleaned_data = data.strip().lower()
    if cleaned_data.startswith("prefix"):
        cleaned_data = cleaned_data[6:]
    return cleaned_data

def calculate_and_print_result(data):
    processed_data = process_data(data)
    if len(processed_data) > 10:
        result = "Long result"
    else:
        result = "Short result"
    print(f"The result is: {result}")

# Использование сложной функции
calculate_and_print_result("  PrefixExample  ")

Рефакторинг:

def clean_data(data):
    cleaned_data = data.strip().lower()
    if cleaned_data.startswith("prefix"):
        cleaned_data = cleaned_data[6:]
    return cleaned_data

def determine_result_length(data):
    return "Long result" if len(data) > 10 else "Short result"

def print_result(result):
    print(f"The result is: {result}")

# Использование разделенных функций
input_data = "  PrefixExample  "
cleaned_data = clean_data(input_data)
result = determine_result_length(cleaned_data)
print_result(result)

Аннотации типов и описания функций (docstrings)

Аннотации (Type Annotations):

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

Пример аннотации типов:

def add_numbers(x: int, y: int) -> int:
    return x + y

В этом примере x: int и y: int указывают, что ожидаемые типы для аргументов функции add_numbers — это целые числа (int), и -> int указывает, что функция возвращает целое число.

Docstring:

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

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

def add_numbers(x, y):
    """
    Функция для сложения двух чисел.

    Параметры:
    x (int): Первое слагаемое.
    y (int): Второе слагаемое.

    Возвращает:
    int: Сумма двух чисел.
    """
    return x + y

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

Объединение аннотаций типов и docstring создает информативное и самодокументированное API, что помогает другим разработчикам и инструментам лучше понимать ваш код и использовать его правильно.

Итоговое задание

Задание 6.

def process_data(data, option):
    if option == 'uppercase':
        processed_data = data.upper()
    elif option == 'lowercase':
        processed_data = data.lower()
    elif option == 'capitalize':
        processed_data = data.capitalize()
    else:
        processed_data = data

    if option != 'original':
        print(f"The processed data is: {processed_data}")
    else:
        print("No processing applied. Original data is:", processed_data)

def calculate_square_area(side_length):
    area = side_length * side_length
    return area

def calculate_circle_area(radius):
    area = 3.14 * radius * radius
    return area

# Пример использования функций
data_to_process = "example string"
process_data(data_to_process, 'uppercase')
process_data(data_to_process, 'capitalize')
process_data(data_to_process, 'lowercase')
process_data(data_to_process, 'original')

square_side = 5
square_area = calculate_square_area(square_side)
print(f"The area of the square is: {square_area}")

circle_radius = 3
circle_area = calculate_circle_area(circle_radius)
print(f"The area of the circle is: {circle_area}")

Задание на рефакторинг:

1. Выделите блоки кода в функции для каждого вида обработки данных (‘uppercase’, ‘lowercase’, ‘capitalize’, ‘original’). Используйте осмысленные названия для функций.
2. Создайте единую функцию для обработки данных, которая принимает данные и тип обработки в качестве параметров.
3. Уберите лишний вывод внутри функции process_data и верните результат обработки.
4. Создайте обобщенную функцию для вычисления площади фигуры, которая принимает тип фигуры и необходимые параметры.
5. Убедитесь, что имена функций и переменных следуют стандартам PEP8.
6. Используйте строки документации (docstrings) для функций, чтобы описать их назначение.
7. В конце кода, напишите комментарий, описывающий, как теперь можно использовать эти функции для обработки данных и вычисления площади фигур.