Разработчик разработчику:

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

Игорь Стариков / idle sign

Видео выступления

Автор

  • Несу Python в массы:
    • Рассказываю о нём
    • Поддерживаю сайт — pythonz.net
    • Перевожу и озвучиваю доклады с PyCon US
  • Пишу код и отдаю его людям — 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

Каркас проекта

Инструменты для быстрого развёртывания структуры проекта.

Организационные вопросы

  • Версии
  • Доступность дистрибутива
  • Поддержка пользователей

Версии

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

Доступность проекта

  • Доступность дистрибутивов. PyPI
  • Доступность исходного кода. GitHub

Поддержка пользователей

  • Нужна система отслеживания инцидентов/ошибок
  • По возможности старайтесь отвечать на вопросы о проекте
  • Хорошо, если есть место для обсуждения: конференция, форум и т.п.
  • Важна доброжелательность
  • При отсутствии возможности решить задачу, обозначьте альтернативные варианты

Спасибо за внимание!

Оригинальная статья «Азбука вежливости разработчика» — http://bit.ly/pypolite

Вопросы?

idlesign   idlesign   idlesign  

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