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

Документирование

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

Если быть точным, то знакомство начинают со Введения (readme) — файла, где сжато, обзорно описываются основные свойства приложения. Не пытайтесь уместить в этот файл всю документацию: задача этого файла привлечь внимание к приложению, а не полностью описать его. Не наполняйте его информацией, которой там не место: например, список изменений принято оформлять отдельным файлом.

Познакомиться с приложением плотнее позволяет документация API. Цель этой документации не столько описать доступные интерфейсы, сколько предоставить примеры, шаблоны использования приложения, указать на нюансы. Для составления документации можно использовать Sphinx, для обнародования — Read The Docs. Не злоупотребляйте автогенерацией документации из исходного кода — часто такой документации недостаточно полноты для восприятия приложения. Документация должна быть доступна хотя бы на одном языке (это язык целевой аудитории, не обязательно английский).

Журнал изменений (changelog) должен быть неотъемлемой частью вашего приложения. Из него другие разработчики смогут узнать о произошедших в выпуске изменениях (даже автоматизировано, например, используя All My Changes), чтобы понять к чему готовиться. Выберите формат и придерживайтесь его. Рекомендации по ведению журнала изменений можно почерпнуть из Keep a Changelog. Не забывайте указывать в этом файле все значащие события (в т.ч. устаревание и удаление той или иной функциональности).

Документирование внутри кода (docstrings) — важная вещь, которая даже регламентирована отдельным PEP 257. Пожалуй, данное PEP может показаться чересчур, однако, все публичные точки программных интерфейсов должны быть документированы, чтобы другие разработчики понимали как их использовать. Иногда полезно документировать и типы данных на входе/выходе, чтобы помочь среде разработки (IDE), которая, в свою очередь, поможет использующим ваш код.

Комментарии внутри кода там, где они требуются для понимания происходящего, приветствуются. Не приветствуются комментарии о погоде, сетования на качество кода и т.п.. Перед написанием комментария следует подумать: если нечего сказать — лучше промолчать; если хочешь и можешь сделать лучше, то сделай, а иначе — лучше промолчать. Последнее замечание, в частности, относится к комментариям TODO и FIXME относящимся к чужому коду. Кстати, TODO — читай как «Добавить функциональность», а FIXME как «Не забудь поправить».

Предупреждения об устаревании (deprecation warnings) тоже отчасти являются формой документирования, поэтому ими тоже не стоит пренебрегать. Неплохо, если в таких предупреждениях указан номер версии, в которой функциональность будет исключена. Замечательно, если предупреждение содержит рекомендацию, какой механизм следует использовать взамен устаревшего — это позволит другим разработчикам более легко мигрировать на новые версии вашего приложения.

И помните: документация должна находиться в актуальном состоянии.

Код

Важной составляющей успеха является стиль оформления кода. Основы стиля регламентирует PEP 8, однако требования к нему могут быть дополнены/изменены исходя из соглашений, принятых для вашего приложения (само собой, если таковые имеются, то они должны быть документированы и доступны для ознакомления всем желающим).

При проектировании и написании приложения (особо библиотеки) следует придерживаться принципа наименьшей неожиданности. Его можно успешно применять сразу ко многим аспектам: к структуре приложения — компонуйте модули и вложенные пакеты выделяя логические единицы, создавайте иерархии; к именованию сущностей — следите, чтобы имена отражали суть вещей, чтобы во флакончике с надписью «кит» не оказался тетраэдр; к последовательности аргументов в однотипных функциях и пр..

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

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

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

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

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

Более важными вопросами являются вопросы доступности пакета приложения и доступности исходного кода. После оформления вашего приложения в пакет хорошо разместить этот пакет на PyPI, чтобы желающие могли скачать его оттуда. При этом будет невежливо опубликовать на PyPI только описание пакета, без возможности получать дистрибутив средствами типа pip (такая возможность на сайте до сих пор имеется, но пользоваться ею не стоит). Код правильней будет разместить на каком-нибудь общедоступном сервисе репозиториев, например, GitHub. Это позволит другим разработчикам участвовать в процессе разработки приложения и, возможно, продлит ему жизнь.

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


Будьте вежливы с пользователями и другими разработчиками.
Что бы вам не казалось, они тоже люди %)