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

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

lirikne 24.08.13 в 04:17

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

lirikne 24.08.13 в 04:18

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

lirikne 24.08.13 в 04:29

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

lirikne 24.08.13 в 04:30

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

lirikne 24.08.13 в 04:31

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

lirikne 24.08.13 в 04:32

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

lirikne 24.08.13 в 04:33

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

lirikne 24.08.13 в 04:34

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

lirikne 24.08.13 в 04:37

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

lirikne 24.08.13 в 07:02

1.2 PEP 8

lirikne 24.08.13 в 07:02

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

lirikne 24.08.13 в 07:06

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

lirikne 24.08.13 в 08:50

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

lirikne 24.08.13 в 08:51

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

lirikne 24.08.13 в 08:52

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

lirikne 24.08.13 в 08:53

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

lirikne 24.08.13 в 09:12

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

lirikne 24.08.13 в 09:21

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

lirikne 24.08.13 в 09:22

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

lirikne 24.08.13 в 09:24

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

lirikne 24.08.13 в 09:41

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

lirikne 24.08.13 в 09:42

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

lirikne 24.08.13 в 09:42

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

lirikne 24.08.13 в 09:58

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

lirikne 24.08.13 в 10:02

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

lirikne 24.08.13 в 10:03

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

lirikne 24.08.13 в 10:03

Пример 1.1

lirikne 24.08.13 в 10:04

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

lirikne 24.08.13 в 10:05

from math import sqrt

lirikne 24.08.13 в 10:05

from os.path import abspath

lirikne 24.08.13 в 10:05

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

lirikne 24.08.13 в 10:06

from django.db import models

lirikne 24.08.13 в 10:06

from django.utils.translation import ugettext_lazy as _

lirikne 24.08.13 в 10:06

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

lirikne 24.08.13 в 10:06

from django_extensions.db.models import TimeStampedModel

lirikne 24.08.13 в 10:13

# Imports from your apps

lirikne 24.08.13 в 10:13

from splits.models import BananaSplit

lirikne 25.08.13 в 07:07

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

lirikne 25.08.13 в 07:09

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

lirikne 25.08.13 в 07:10

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

lirikne 25.08.13 в 07:10

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

lirikne 25.08.13 в 07:11

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

lirikne 25.08.13 в 07:11

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

lirikne 25.08.13 в 07:12

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

lirikne 25.08.13 в 07:14

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

lirikne 25.08.13 в 08:31

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

lirikne 25.08.13 в 08:33

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

lirikne 25.08.13 в 08:48

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

lirikne 25.08.13 в 08:50

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

lirikne 25.08.13 в 08:50