Готовый перевод Two Scoops of Django / Двойное мороженное из Django: Стиль кода

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

1.1 Важность создания читаемого кода

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

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

Избегайте сокращения имен переменных.

Расписывайте имена аргументов функций.

Документируйте ваши классы и методы.

Выносите повторяющиеся строки кода в многократно используемые функции и методы.

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

Возьмем к примеру надоедливые сокращенные имена переменный. Когда вы видите название переменной balance_sheet_decrease, это гораздо легче интерпретировать в своем уме, чем сокращенные переменные BSD или bal_s_d. Подобные сокращения могут сэкономить несколько секунд набора текста, но отзовутся вам несколькими часами или днями технического долга. Это того не стоит.

1.2 PEP 8

PEP 8 является официальным руководство по стилю для Python. Мы советуем тщательно прочитать и научиться ему следовать: http://www.python.org/dev/peps/pep-0008/

PEP 8 описывает следующие условности кода:

"Используйте 4 пробела для каждого уровня отступа"

"Отделяйте функции верхнего уровня и определения классов двумя пустыми строками."

"Определение метода внутри класса разделяются одной пустой строкой."

Все файлы Python в ваших проектах Django должны придерживаться PEP 8. Если вам сложно запомнить PEP 8, то найдите плагин для вашего редактора кода, который проверяет код при вводе текста.

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

ВНИМАНИЕ: Не изменяйте конвенций существующего проекта.

Стиль PEP 8 относится только к новым проектам Django. Если вы пришли в существующий проект Django, который придерживается иного соглашения, отличного от PEP 8, тогда соблюдайте новые условности.

Пожалуйста, прочтите раздел "Глупое следование является хобгоблином маленьких умов" в PEP 8 чтобы узнать подробнее об этой и других причинах, чтобы нарушать правила: http://2scoops.co/hobgoblin-of-little-minds

1.3 Слово об Импорте

PEP 8 предлагает группировать импорты в следующем порядке:

Импорт стандартных библиотек

Импорт связанный с третьей стороной.

Локальные приложения или конкретные библиотеки

Когда мы работаем над проектом Django, наш импорт выглядит примерно так:

Пример 1.1

# Импот стандартных бибилиотек

from math import sqrt

from os.path import abspath

# Импорт из ядра Django

from django.db import models

from django.utils.translation import ugettext_lazy as _

# Импорт сторонних приложений

from django_extensions.db.models import TimeStampedModel

# Imports from your apps

from splits.models import BananaSplit

(Заметка: Вам не обязательно комментировать ваши импорты, как у нас; комментарии тут лишь для объяснения примера.)

Порядок импорта таков:

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

Импорт из ядра Django

Импорт приложений третьих сторон.

Импорт из приложений, которые вы создали, как часть этого проекта Django. (Вы можете прочитать больше про приложения в главе 4, Основы проектирования приложений.)

1.4 Использование явного относительного импорта.

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

Чтобы проиллюстрировать преимущества явного относительного импорта, давайте рассмотрим пример.

Представьте себе, что в следующем фрагменте от Django проекта, созданного для отслеживания потребления мороженого, учитывая вафли/сахар/пирожное ?конуса, которые вы когда-либо ели.

О нет, ваше приложение содержит жесткий импорт, что очень плохо!

Плохой пример 1.1

# cones/views.py

from django.views.generic \

import CreateView

# НЕ ДЕЛАЙТЕ ТАК!

# Жесткая привязанность к пакету

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

Что если вы захотите повторно использовать приложение "cones" в другом проекте, который отслеживает ваше общее потребление десерта? Вам пришлось бы изменить название из-за конфликта имен (например, конфликт с Django приложением для конусов снега)?

Что если в какой-то момент вы захотите просто изменить название вашего приложения?

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

Давайте теперь исправим плохой фрагмент кода, содержащий жёсткий импорт, в хороший, с явно выраженным относительным импортом. Вот исправленный пример:

Пример 1.2

# cones/views.py

# Относительный импорт пакета 'cones'

Для подведения итога представлена эта таблица разных типов импорта в Python и когда их использовать в проектах Django:

Используется, когда импорт происходит не из текущего приложения

Используется, когда импорт происходит из другого модуля текущего приложения

Часто используется, когда импорт происходит из другого модуля текущего приложения, но это плохой способ

Дополнительная информация: http://www.python.org/dev/peps/pep-0328/

1.5 Избегайте использования Import *

В 99% случаев в работе мы явно импортируем каждый модуль:

Пример 1.3

Никогда не делайте следующего:

Плохой пример 1.2

Внимание! Этот перевод, возможно, ещё не готов.
Его статус: идёт перевод

Переведено на Нотабеноиде
http://notabenoid.org/book/41430/168877

Переводчики: lirikne, wolfmetr