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

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

2. АВТОР
Несу Python в массы:
Рассказываю о нём
Поддерживаю сайт —
Перевожу и озвучиваю доклады с PyCon US
Пишу код и отдаю его людям —
pythonz.net
 idlesign

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

4. ПОЧЕМУ РАССКАЗЫВАЮ ОБ ЭТОМ Я
Несколько десятков проектов с открытым кодом — Python, JavaScript, PHP, Delphi.

5. Вежливость — уважительность,
корректность, соблюдение
приличий.
Вежа — знаток, опытный, знающий.

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

7. README
Сжатое описание продукта, его основные характеристики.
Важная информация
Ссылка на основную документацию

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

9. ЖУРНАЛ ИЗМЕНЕНИЙ
Позволяет пользователю получить представление о необходимости обновления.
Определите формат и строго следуйте ему —
Особое внимание: устаревание, удаление
функциональности
Keep a Changelog

10. ДОКУМЕНТИРОВАНИЕ ВНУТРИ КОДА
Информация о возможностях API, примеры использования.
Не заменяет основную документацию
, как отправная точка
Должны быть покрыты все публичные точки
программых интерфейсов
PEP 257

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

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

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

14. ПРИНЦИП НАИМЕНЬШЕЙ
НЕОЖИДАННОСТИ
Структура приложения: логическое распределение
по модулям, пакетам, пространствам имён
Именование: соответствие наименования
содержимому
Последовательно аргументов в однотипных
функциях
Не усложнять

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

16. ПУТЬ ПИТОНА. ОН ЖЕ ДЗЭН
1. Красивое лучше безобразного.
2. Явное лучше подразумеваемого.
3. Простое лучше сложного.
4. Сложное лучше усложнённого.
5. Плоское лучше вложенного.
6. Разреженное лучше плотного.
7. Важна читабельность.
8. Исключения недостаточно исключительны, чтобы нарушать правила.
Хотя, практичность превыше безупречности.
9. Ошибки не должны оставаться незамеченными.
Если не были заглушены явно.
10. Пред лицом многозначности презрите желание догадываться.
11. Должен быть один — и лучше единственный — очевидный способ достичь цели.
Впрочем, если вы не голландец, поначалу этот способ может казаться не столь
очевидным.
12. Лучше сейчас, чем никогда.
Впрочем, часто никогда лучше, чем прямо сейчас.
13. Если реализацию трудно описать, значит идея была никудышной.
14. Если реализацию легко описать — возможно, идея была хорошей.
15. Пространства имён были блестящей идеей — генерируем ещё!

17. АВТОМАТИЗИРОВАННЫЕ ТЕСТЫ
Не являются гарантией правильного функционирования, но незаменимы при
реорганизации кода.
Позволяют относительно безболезненно развивать
код
Критичность необходимости будет расти с
размерами проекта
Добрую службу сослужит непрерывная интеграция,
например Travis CI

18. КАРКАС ПРОЕКТА
Инструменты для быстрого развёртывания структуры проекта.
2011
2013 *
2013 **
2014
…
Scaffold (scaffold-py)
Cookiecutter
makeapp
PyScaffold

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

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

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

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

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

24. ВОПРОСЫ?
 idlesign  idlesign  idlesign
Эти слайды можно найти тут — http://bit.ly/ist_001