Полное руководство по правильной разметке кода Python по стандарту PEP 8

Разметка Python кода: ПEP 8 правила

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

Отступы и форматирование строк

• Используйте 4 пробела для отступов. Табуляция не рекомендуется.
• Максимальная длина строки – 79 символов. В комментариях и докстрингах – до 72 символов.
• При длинных выражениях продолжайте строку с отступом в 4 пробела относительно начальной строки.

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

• Используйте стиль snake_case для имен переменных и функций (например, var_two).
• Классы именуются в стиле CamelCase.
• Константы пишутся заглавными буквами с подчеркиванием (например, MAX_LIMIT).

Импортирование модулей

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

Комментарии и докстринги

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

Пробелы и операторы

• Ставьте пробелы вокруг операторов и после запятых (например, a = b + c, my_function(a, b, c)).
• Не ставьте пробелы внутри скобок, за исключением случаев, когда это необходимо для читаемости.

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

Основные принципы форматирования

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

Именование переменных и функций играет не менее важную роль. Выбирайте описательные имена, которые помогут вам и вашим коллегам быстро понять, какую роль выполняет та или иная переменная или функция. Например, вместо var_two используйте qualified_dividends, а вместо do_three – calculate_tax.

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

import os
import sys
import requests
import my_module

Также следует помнить о длине строк. Максимальная длина строки не должна превышать 79 символов, что обеспечивает удобочитаемость кода на экранах с различными разрешениями. Если строка слишком длинная, перенесите ее на следующую строку с использованием обратной косой черты или скобок.

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

string_one = 'Это строка'
string_two = 'Еще одна строка'

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

Дополнительно, вы можете использовать автоформаттеры и другие инструменты для автоматического приведения вашего кода в соответствие с существующим стандартом. Эти инструменты помогут вам экономить время и избежать ошибок. Например, вы можете воспользоваться такими инструментами, как black или autopep8.

Отступы и длина строки

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

Что касается длины строки, оптимальная длина составляет не более 79 символов. Это связано с тем, что строки большей длины могут быть трудны для восприятия и заставлять читателя прокручивать экран. Длинные строки можно разбивать на несколько строк с использованием обратного слэша (\) или скобок. Например, функция, которая суммирует числа в списке, может быть написана так:

def sumnums(list_of_numbers):
total = sum(
list_of_numbers)  # каждая длинная строка должна быть разбита
return total

Не забывайте оставлять пробелы вокруг операторов и после запятых для улучшения читаемости. Например, вместо total=sum(list_of_numbers) пишите total = sum(list_of_numbers). Это правило помогает избегать ошибок и делает ваш код более читаемым.

При импорте модулей следует размещать каждый импорт на отдельной строке. Так будет проще найти нужный модуль и избежать дублирования. Например:

import os
import sys

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

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

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

Когда вы следуете определенным правилам именования, ваш код становится более структурированным и понятным. Важно избегать использования непонятных сокращений и давать переменным и функциям осмысленные имена. Например, вместо n лучше использовать number, а вместо tmp – temporary_value.

Для переменных и функций предпочтительно использовать snake_case стиль, то есть слова разделяются нижними подчеркиваниями. Например: this_is_one_thing и qualified_dividends. Это значительно повышает читаемость и делает код более структурированным.

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

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

Когда вы работаете с классами и модулями, важно следовать тем же принципам. Имена классов обычно записываются в стиле CamelCase, например: DataProcessor. Это помогает отличать их от переменных и функций.

Комментарии также играют важную роль в понятности кода. Если название переменной или функции недостаточно очевидно, не стесняйтесь оставлять пояснения в комментариях. Например:

# Временное значение для хранения промежуточного результата
temporary_value = 0

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

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

Структура и оформление кода

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

Имена переменных и функций также играют важную роль в читаемости. Используйте говорящие имена, которые отражают суть переменной или функции. Например, вместо var_three лучше использовать total, если эта переменная хранит итоговое значение. Для функций используйте глаголы, которые описывают действия, например, calculate_total, do_three_tasks.

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

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

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

import os
import sys
import requests
from mymodule import my_function

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

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

Импорт модулей

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

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

• Группировка импортов: Импорты следует разделять на три группы: стандартные библиотеки, сторонние библиотеки и собственные модули. Между этими группами оставляйте пустые строки. Например:

  
  import os
  import sys
  import numpy as np
  import pandas as pd
  import my_module
  

• Избегайте импорта всего модуля: Не рекомендуется использовать конструкции типа from module import *, так как это делает код менее читаемым и может привести к конфликтам имен. Вместо этого явно импортируйте необходимые элементы.

  
  from math import sqrt, pi
  

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

  
  import numpy as np
  import matplotlib.pyplot as plt
  

• Соблюдение алфавитного порядка: Внутри каждой группы импорты должны быть расположены в алфавитном порядке. Это облегчает их поиск и добавляет структурированности.

  
  import os
  import sys
  import numpy as np
  import pandas as pd
  import my_module
  import my_other_module
  

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

  
  def calculate_area(radius):
  from math import pi
  return pi * radius ** 2
  

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

Видео:

Простой способ замерить скорость работы кода в python