Readme-driven development

Вряд ли найдется на этой планете противник ТЗ. ТЗ позволяет защитить разработчиков, менеджеров и сам продукт от неминуемо бурной фантазии заказчика.

Это гарант того, что проект однажды будет завершен. Понимание задачи — одно из самых важных этапов в решении оной.

ТЗ поможет встать на ноги любому проекту, даже если вы занимаетесь разработкой собственной open source библиотеки.

И самое лучшее ТЗ для open source — readme.

Документацию принято писать после того, как написан код. Я считаю этот подход неверным.

Те, кто хотя бы однажды ощутили пользу от TDD (test-driven development) согласятся, что писать тесты после кода, это как анестезия после операции. Это больно.

Если вы не знаете, зачем писать тесты перед кодом (или вообще зачем писать тесты), рекомендую обратиться к Википедии ^[1].

Если тесты необходимо писать перед кодом, то документация к библиотеке должна быть написать еще до того, как будет написаны тесты.

Когда дело касается собственного проекта, бурная фантазия просыпается у каждого. Все хотят светлого будущего для своего детища, и никто не упустит шанс сделать его еще чуточку лучше.

Readme написанный до того, как появится первая строчка кода, поможет правильно понять задачу и не ошибиться в деталях её реализации.

И вы удивитесь, насколько просто писать тесты, когда есть готовый readme.

Этот подход называется readme-driven development, впервые озвученный Томом Перстон-Вернером ^[2] (Tom Preston-Werner), CEO GitHub.

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

Это не утопия, это реальный способ сделать важу жизнь проще, а проект лучше. Я разработал не один open source проект, руководствуясь этим принципом и знаю о чем говорю. Если сомневаетесь — просто попробуйте.

Автор: kossnocorp