Python пред-спецификация для написания ПРИЛОЖЕНИЯ

Пред-спецификация основана на книгах:

Искусство чистого кода | Майер Кристиан

Python Чистый код для продолжающих | Эл Свейгарт

Секреты Python Pro | Дейн Хиллард

 

Правила написания кода разделены на написание: библиотеки (фреймворка) или приложения (рабочей программы).

В данной спецификации будут правила для написания ПРИЛОЖЕНИЯ.

Искусство чистого кода | Майер Кристиан#

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

…

В рамках одного программного проекта отбросьте весь ненуж-
ный функционал и сосредоточьтесь на минимально жизнеспо-
собном продукте

По возможности пишите простой и лаконичный код.

…

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

…

Следуйте философии Unix, которая гласит, что каждая функ-
ция кода должна быть нацелена на выполнение лишь одной
задачи («Do One Thing Well»).

страница 29-30

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

страница 32

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

страница 33

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

страница 34

Принцип 4. Соблюдайте правила именования

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

…

Выбирайте описательные имена. Допустим, вы создаете функ-
цию для конвертации валют из долларов США (USD) в евро
(EUR) в Python. Назовите ее usd_to_eur(amount), а не f(x).

Выбирайте недвусмысленные имена. Вы можете подумать,
что имя dollar_to_euro(amount) будет хорошим названием для
функции конвертации валюты. Конечно, оно лучше, чем f(x), но
оно хуже, чем usd_to_eur(amount), потому что вносит ненужную
двусмысленность. Что вы имеете в виду: доллары США, Канады
или Австралии? Если вы находитесь в Соединенных Штатах,
ответ будет для вас очевиден, но австралийский программист
может не знать, что код написан в США, и может сделать другой
вывод. Сведите к минимуму такие недоразумения!

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

Используйте именованные константы, а не магические чис-
ла. В вашем коде может несколько раз встречаться магическое
число 0.9 в качестве коэффициента для преобразования суммы
в долларах США в сумму в евро. Однако читатель кода (и вы
сами в будущем) вынужден будет задуматься над назначением

этого числа. Оно не является самоочевидным. Гораздо лучший
способ обращения с магическим числом 0.9 — это сохранить его
в переменной, имя которой состоит из прописных букв (обычно
так обозначаются константы), например CONVERSION_RATE = 0.9,
и использовать ее в качестве коэффициента при расчетах с кон-
вертацией валют. Например, вы можете вычислить свой доход
в евро как income_euro = CONVERSION_RATE * income_usd.

страницы 108-109

Принцип 7. Избегайте ненужных комментариев

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

Не используйте встроенные комментарии. Их можно полностью избежать, выбирая осмысленные имена переменных.

Не добавляйте очевидные комментарии. …

Не надо комментировать старый код, просто удаляйте его. …

стр. 114-116

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

Этот принцип является одним из золотых правил при разработке эффективных приложений и взаимодействия с пользователем.
стр. 116-117

Принцип 9. Не повторяйтесь

Не повторяйтесь (Don’t repeat yourself, DRY) — это общепризнанный интуитивно понятный принцип, который рекомендует избегать повторяющегося кода.

Принцип 10. Принцип единой ответственности

Принцип единой ответственности (single responsibility principle) означает, что каждая функция должна выполнять только одну главную задачу.

Как правило, каждый класс и каждая функция должны иметь только одну ответственность (обязанность). Роберт К. Мартин, автор этого принципа, понимает ответственность как причину для изменения. Таким образом, для него золотой стандарт определения класса или функции — ограничить их выполнением одной обязанности.

Принцип 11. Тестируйте

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

Принцип 12. Малое — прекрасно

Малый код — это код, который требует относительно небольшого количества строк для выполнения одной конкретной задачи.

Принцип 13. Закон Деметры

Важной концепцией системы Demeter является разделение про-
граммного обеспечения как минимум на две части. Первая опре-
деляет объекты, а вторая — операции. Целью системы Demeter
является поддержание слабой связанности между объектами
и операциями, чтобы можно было вносить изменения в один
элемент без серьезного влияния на другой. Это значительно со-
кращает время на поддержку ПО.
Другими словами, вы должны минимизировать зависимость между
объектами кода. Уменьшая ее, вы снижаете сложность кода и, соот-
ветственно, повышаете удобство сопровождения. Из этого следует,
например, что каждый объект должен вызывать только методы
смежных объектов (или собственные), но не может вызывать методы
объектов, которые он получает в результате вызова метода соседнего
объекта. Для пояснения давайте определим: если объект A вызыва-
ет методы объекта B, то A и B считаются друзьями. Все просто. Но
что, если метод B ссылается на объект C? Теперь объект A может
выполнять что-то вроде этого: B.method_of_B().method_of_C(). Это
называется цепочкой вызовов методов — в нашем случае выходит,
что вы общаетесь с другом вашего друга. Закон Деметры гласит:
разговаривай только со своими близкими друзьями, поэтому он за-
прещает создание цепочек методов такого типа.

Принцип 14. Вам это никогда не понадобится

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

…

Смысл в том, что нужно избегать чрезмерной инженерии (overen-
gineering): создания продукта, который является производительнее
и надежнее или содержит больше функций, чем это необходимо.
Это добавляет излишнюю сложность, что должно немедленно вас
насторожить.

…

Всегда выбирайте в первую очередь легкий путь.

Принцип 15. Не используйте слишком много уровней отступов

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

Лучше меньше, да лучше

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

Введение в философию Unix
Основная идея философии Unix заключается в создании простого,
ясного, лаконичного модульного кода, который легко расширять
и поддерживать. Это может означать многое …, но главное — позволить большому
количеству людей совместно работать над кодовой базой, отдавая
при этом предпочтение легкости чтения кода, а не его эффективно-
сти, и компонуемости вместо монолитного дизайна.

1. Пусть каждая функция делает хорошо что-то одно
Всеобъемлющий принцип философии Unix — делай что-то одно, но делай это хорошо.

2. Простое лучше сложного

Дзен Python от Тима Петерса (Tim Peters)
Красивое лучше уродливого.
Явное лучше неявного.
Простое лучше сложного.
Сложное лучше запутанного.
Плоское лучше вложенного.
Разреженное лучше плотного.
Читаемость имеет значение.
Особые случаи не настолько особые, чтобы нарушать правила.
При этом практичность важнее безупречности.
Ошибки никогда не должны замалчиваться.
Если они не замалчиваются явно.
Встретив двусмысленность, отбрось искушение угадать.
Должен существовать один (желательно только один) очевидный способ
сделать это.
Хотя этот способ поначалу может быть и неочевиден, если вы не
голландец.
Сейчас лучше, чем никогда.
Хотя никогда зачастую лучше, чем *прямо* сейчас.
Если реализацию сложно объяснить — идея плоха.
Если реализацию легко объяснить — возможно, идея хороша.
Пространства имен — отличная штука! Будем использовать их чаще!

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

Уменьшение сложности
Чем длиннее код, тем он сложнее для понимания

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

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

8. Отделяйте UI от функциональности

11. Чистый код лучше умного

Этот принцип подчеркивает компромисс между чистым и умным кодом: код не должен быть умным в ущерб простоте.

13. Делайте свой код робастным

Как программист вы потенциально можете испортить код, просто
изменив его. Поэтому кодовая база должна быть устойчива к изме-
нениям (robust against changes), чтобы даже небрежный программист
мог работать с кодовой базой, не нарушая ее функциональности.

…

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

…

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

14. Исправляйте то, что можете, но лучше, если сбой
случится раньше и громко

Ошибки могут накапливаться. …

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

Глава 8. В дизайне лучше меньше, да лучше

Минимализм в поисковых системах

минималистичный и чистый дизайн — не случайность

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

Свободное пространство
Свободное (пустое) пространство — один из ключевых элементов минималистичного дизайна.

«Субтрактивное»1 мышление, возможно, кажется не совсем есте-
ственным, однако замена элементов дизайна пустым пространством
повышает наглядность представления информации и приводит
к более сфокусированному UX. С помощью этого подхода успешным
компаниям удается сохранить главное в своих приложениях — сфо-
кусированность и заточенность на определенную задачу. Напри-
мер, на целевой странице Google много свободного пространства,
а Apple использует его на презентациях продукции. Думая о своих
пользователях, помните следующее: если вы собьете их с толку, вы
их потеряете. Свободное пространство добавляет строгости пользо-
вательским интерфейсам.

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

…

Уменьшение хаоса и усиление фокуса, скорее всего, повысят коэффициент конверсии страницы заказа за счет улучшения UX.

Снижайте количество шрифтов и цветов

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

Будьте последовательны

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

Оружие против сложности

сложность ведет к хаосу

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

Python Чистый код для продолжающих | Эл Свейгарт#

 

 

Секреты Python Pro | Дейн Хиллард#