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

Сегодня познакомлю вас с инструментом, который приведет все к единому стилю, а также укажет на возможные ошибки - PEP8, рекомендованный создателями Python

Быстрый ликбез ?

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

Также помимо PEP8 существует целое множество разных стандартов: Pylint, Pyright, Ruff и другие. Так что можете выбрать любой в зависимости от своей задачи и проекта

Причины использовать ?

PEP8 - это целое руководство по тому, как писать код на Python. Оно содержит рекомендации и правила, которых стоит придерживаться, когда пишете код. Если каждый из команды будет следовать этим правилам, то на выходе мы получим проект, написанный "одним" человеком

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

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

Кроме того, многие редакторы кода или IDE поддерживают стандарты PEP8 и могут автоматически проверять ваш код на соответствие этим стандартам

В целом, соблюдение стандартов PEP8 - это важная практика для написания качественного кода на Python. Она помогает сделать ваш код более читаемым, понятным и устойчивым к ошибкам, что делает его более удобным для совместной работы и поддержки в будущем

Давайте побыстрее посмотрим на часть из правил PEP8, так как уже сейчас существует более 100 указаний!

Отступы ?

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

# Правильно, используем 4 пробела
if x == 1:
    print("x is 1")

# Неправильно, 1000 пробелов...
if x == 1:
                   print("x is 1")

Максимальная длина строки ?

Ограничьте длину строки 79 символами или меньше. Если строка длиннее, то лучше разбить ее на несколько строк. Длинные строки могут быть сложными для чтения, особенно если они выходят за границы редактора. Хорошей практикой является разбиение длинных строк на несколько строк с помощью символа обратной косой черты \

# Правильно
# Если строка длинная - удобно ее перенести на следующую строку
long_string ="This is a really long string that" \
                            "spans multiple lines"

# Неправильно
# Слишком громоздко
long_string = "This is a really long string that spans multiple lines"

Пробелы ?

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

# Правильно
# Везде по одному пробелу
x = 2 + 3
y = (1 + 2) * 3

# Неправильно
# Как будто макароны слиплись
x=2+3
y =   ( 1 + 2  ) *  3 # уже разлиплись

Нейминг ?

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

# Правильно
# По названию переменной понятно, что в ней хранится
age = 25
name = "John"
# То же самое и с функциями
def calculate_sum(numbers):
    return sum(numbers)

  # Неправильно
  # Что хранится в a, b?
  a = 25
  b = "John"
  def calc_s(n):
    return sum(n)

Комментарии ?

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

from datetime import datetime

# Правильно
# Получаем текущую дату и время
current_time = datetime.now()

# Неправильно
current_time = datetime.now() # Получаем текущую дату и время

Импорты ?

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

# Правильно
import datetime
import os

from math import sqrt

import requests

# Неприавльно
import requests, os, datetime

from math import *

Пробелы вокруг операторов ?‍?️

Для разделения логически связанных частей кода используйте пустые строки. Не объединяйте несколько операторов в одну строку. Ставьте пробелы вокруг операторов (+, -, *, /, //,% и т. д.), но не нужно ставить их вокруг символа индексирования или среза.

# Правильно
# Читаемость повышается, когда между операторов пробелы
l = [1, 2, 3]
x = 2 + 3
y = x * 4
z = l[0]

# Неправильно
# Неоднородно, поэтому тяжело понять, что написано с первого взгляда
x=2+3
y = x*4
z = l  [0]

Названия функций и методов ?

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

# Правильно
# Название функций с маленькой буквы и разделены _
def calculate_sum(numbers):
  return sum(numbers)

def get_user_name(user):
  return user.name

# Неправильно
# Java style - not Python
def numbresSum(nums):
  return sum(nums)

# Каша в названиях. Функция называется user и принимает user и еще непонятно что делает
def user(user):
  return user.name

Расположение функций и классов ?

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

# Правильно
# Все что используете в коде должно быть описано выше
def calculate_sum(numbers):
  return sum(numbers)

def main():
  list_of_numbers = [1, 2, 3, 4]
  total_sum = calculate_sum(list_of_numbers)
  print(f"The total sum is: {total_sum}")

if __name__ == "__main__":
    main()

# Неправильно
# Каша-машала
def main():
  list_of_numbers = [1, 2, 3, 4]
  total_sum = calculate_sum(list_of_numbers)
  print(f"The total sum is: {total_sum}")

def calculate_sum(numbers):
  return sum(numbers)

if __name__ == "__main__":
    main()

Тройные кавычки ?

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

# Правильно
# В документацию стоит добавлять: описание функции, атрибуты и что возвращает
def calculate_sum(numbers):
  """
  This function calculates the of the numbers in the given list.

  Parameters:
    numbers (list): A list of numbers to calculate the sum of.

  Returns:
    float: The sum of numbers in list.
  """
  return sum(numbers)

# Неправильно
# Все написать в одну строчку ?
def calculate_sum(numbers):
  # This function calculates the of the numbers in the given list.
  return sum(numbers)

Линтеры ⛏️

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

Линтеры — это инструменты, которые анализируют код и проверяют, соответствует ли он стандартам PEP8. Если в коде есть нарушения стандартов или другие проблемы, линтеры предупреждают об этом разработчика. Некоторые из наиболее популярных линтеров для Python:

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

flake8 — это линтер, который проверяет соответствие кода стандартам PEP8, а также обнаруживает другие проблемы в коде, такие как неиспользуемые импорты и неправильное форматирование строк.

PyCharm — это IDE для Python, которая включает встроенный линтер, который проверяет соответствие кода стандартам PEP8 и другие проблемы в коде. Он также предлагает рекомендации по исправлению нарушений стандартов PEP8.

VS Code - редактор кода, который направлен на простоту использования и на расширяемость. Так существует целый магазин расширений, из которых вы можете собрать целое IDE под себя. Если все правильно настроить, то обойдет даже PyCharm

Автоматические форматировщики ?

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

Black - это автоматический форматировщик кода на Python, который форматирует код в соответствии со стандартами PEP8. Он удаляет неоднозначность в коде и делает его более понятным.

Autopep8 - это инструмент, который автоматически форматирует код в соответствии со стандартами PEP8. Он также может исправлять другие проблемы в коде, такие как синтаксические ошибки.

YAPF - это автоматический форматировщик кода на Python, который форматирует код в соответствии со стандартами PEP8 и другими рекомендациями по стилю кодирования.

Использование линтеров и автоматических форматировщиков существенно упрощает процесс следования стандартам PEP8 и улучшает качество кода.

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

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

Подытожим

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

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