Upload
pynsk
View
181
Download
1
Embed Size (px)
Citation preview
РАЗРАБОТЧИК РАЗРАБОТЧИКУ:
АЗБУКА ВЕЖЛИВОСТИИгорь Стариков / 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