Азбука вежливости

РАЗРАБОТЧИК РАЗРАБОТЧИКУ:

АЗБУКА ВЕЖЛИВОСТИИгорь Стариков / idle sign

АВТОРНесу Python в массы:Рассказываю о нёмПоддерживаю сайт — Перевожу и озвучиваю доклады с PyCon US

Пишу код и отдаю его людям —

pythonz.net

idlesign

ПОЧЕМУ Я РАССКАЗЫВАЮ ОБ ЭТОМАктуальноИнтересноВажно

ПОЧЕМУ РАССКАЗЫВАЮ ОБ ЭТОМ Я

Несколько десятков проектов с открытым кодом — Python, JavaScript, PHP, Delphi.

Вежливость — уважительность,корректность, соблюдение

приличий.

Вежа — знаток, опытный, знающий.

ДОКУМЕНТИРОВАНИЕДокументация — основное средство начального ознакомления с возможностями продукта,

влияющее на формирование отношения к нему.

ДоступностьАктуальное состояниеВерный выбор целевой аудитории

READMEСжатое описание продукта, его основные характеристики.

Важная информацияСсылка на основную документацию

ОСНОВНАЯ ДОКУМЕНТАЦИЯПримеры, нюансыИнструменты: , Не увлекайтесь автодокументированием по даннымкода

Sphinx Read The Docs

ЖУРНАЛ ИЗМЕНЕНИЙПозволяет пользователю получить представление о необходимости обновления.

Определите формат и строго следуйте ему —

Особое внимание: устаревание, удалениефункциональности

Keep a Changelog

ДОКУМЕНТИРОВАНИЕ ВНУТРИ КОДАИнформация о возможностях API, примеры использования.

Не заменяет основную документацию, как отправная точка

Должны быть покрыты все публичные точкипрограммых интерфейсов

PEP 257

КОММЕНТАРИИ ВНУТРИ КОДАТолько, если требуются для улучшения понимания происходящего.

Не нравится качество кода — исправь. Не можешьисправить — промолчиНе ставьте TODO и FIXME к чужому коду

ПРЕДУПРЕЖДЕНИЯ ОБ УСТАРЕВАНИИМодуль warnings, функция warn. Классы:DeprecationWarning и PendingDeprecationWarningВывести номер версии, в которой устареетВывести рекомендацию об альтернативноммеханизме

КОДСоглашение о стиле. Принцип наименьшей неожиданностиПринцип разумных умолчанийПуть Питона. Он же Дзэн

PEP 8

ПРИНЦИП НАИМЕНЬШЕЙНЕОЖИДАННОСТИ

Структура приложения: логическое распределениепо модулям, пакетам, пространствам имёнИменование: соответствие наименованиясодержимомуПоследовательно аргументов в однотипныхфункцияхНе усложнять

ПРИНЦИП РАЗУМНЫХ УМОЛЧАНИЙТребует анализа/прогноза вариантовиспользования кодаСоздать инструменты для частых сценариевГибкие реализации и реализации общего видапредпочтительныНе усложнять

ПУТЬ ПИТОНА. ОН ЖЕ ДЗЭН1. Красивое лучше безобразного.2. Явное лучше подразумеваемого.3. Простое лучше сложного.4. Сложное лучше усложнённого.5. Плоское лучше вложенного.6. Разреженное лучше плотного.7. Важна читабельность.8. Исключения недостаточно исключительны, чтобы нарушать правила.

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

Если не были заглушены явно.10. Пред лицом многозначности презрите желание догадываться.11. Должен быть один — и лучше единственный — очевидный способ достичь цели.

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

12. Лучше сейчас, чем никогда.Впрочем, часто никогда лучше, чем прямо сейчас.

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

АВТОМАТИЗИРОВАННЫЕ ТЕСТЫНе являются гарантией правильного функционирования, но незаменимы при

реорганизации кода.

Позволяют относительно безболезненно развиватькодКритичность необходимости будет расти сразмерами проектаДобрую службу сослужит непрерывная интеграция,например Travis CI

КАРКАС ПРОЕКТАИнструменты для быстрого развёртывания структуры проекта.

2011 2013 *2013 **2014 …

Scaffold (scaffold-py)CookiecuttermakeappPyScaffold

ОРГАНИЗАЦИОННЫЕ ВОПРОСЫВерсииДоступность дистрибутиваПоддержка пользователей

ВЕРСИИНомер версии — это и договорённость и визитнаякарточка. Следует придерживаться правил« ».Частота выпуска: «когда нельзя больше ждать»,«когда накопилось», «когда будет готово»

Осмысленной нумерации

ДОСТУПНОСТЬ ПРОЕКТАДоступность дистрибутивов. Доступность исходного кода.

PyPIGitHub

ПОДДЕРЖКА ПОЛЬЗОВАТЕЛЕЙНужна система отслеживания инцидентов/ошибокПо возможности старайтесь отвечать на вопросы опроектеХорошо, если есть место для обсуждения:конференция, форум и т.п.Важна доброжелательностьПри отсутствии возможности решить задачу,обозначьте альтернативные варианты

СПАСИБО ЗА ВНИМАНИЕ!Оригинальная статья «Азбука вежливости разработчика» — http://bit.ly/pypolite

ВОПРОСЫ?       idlesign idlesign idlesign

Эти слайды можно найти тут — http://bit.ly/ist_001