README-driven Development

Перевод | Автор оригинала: Pascal Hertleif

Как и большинство других (\w) методов DD1, «разработка под управлением README» направляет ваш подход к разработке программного обеспечения. Этот подход лучше всего работает для небольших автономных проектов или библиотек, поверхность API которых не больше, чем умещается в кучке заметок. И, конечно же, для проектов, о которых вы, возможно, не захотели писать прямо сейчас, а просто подумали в душе, это показалось хорошей идеей.

Предпосылка проста:

Перед написанием любого кода напишите файл README, описывающий, что должно делать ваше программное обеспечение.

(Я обычно называю файл README.md и использую синтаксис Markdown, но вы, конечно, можете делать все, что захотите.)

tl;dr

• Опишите все
  • На примере
• Что вы хотите, чтобы ваше программное обеспечение выполняло
• И опубликуйте README

Опишите все

Помимо обычной метаинформации вроде

• общее описание проекта,
• имя авторов,
• ссылки на другие страницы (например, сгенерированная документация по API),
• лицензия, под которой это опубликовано,
• и, возможно, текущий статус сборки,

ваш файл README должен содержать довольно точное описание того, как использовать это программное обеспечение.

Эти вопросы могут помочь:

• Что вам нужно написать, чтобы показать, как этим пользоваться?
• Какие функции вам нужно показать, чтобы пользователь (и разработчик!) Понял - к чему вы стремились?
• Как вы хотите использовать вашу программу / библиотеку?

Замечательно то, что вы не описываете текущее состояние существующего проекта, а описываете идеальное состояние, которое вы хотели бы иметь.

На примере

Допустим, вы хотите написать библиотеку, которая может извлекать наиболее доминирующие цвета из файла изображения2: вам нужно показать

1. как загрузить библиотеку,
2. какие функции / структуры данных может использовать пользователь,
3. как загрузить изображение,
4. а затем, какие данные вы получите обратно.

Представьте себе наиболее удобный для этого API и запишите его.

Что вы хотите, чтобы ваше программное обеспечение выполняло

Рассматривайте свой README как тестовый файл - буквально! Структурируйте примеры (кода) таким образом, чтобы их можно было запустить и они работали (после того, как вы написали код).

Вы можете использовать такие инструменты, как скептик, чтобы извлекать блоки кода из файлов Markdown и запускать их как модульные тесты.

И опубликуйте README

После того, как вы написали файл README, вы должны его опубликовать. Вероятно, с большим предупреждением «ЭТО ПРОСТО ИДЕЯ ТАК ДАЛЕКО». Может быть, просто как Gist, но определенно в том месте, где вы (или другие) можете легко начать реализацию описанных вами функций.

После публикации этого сообщения Солти Рандо сообщил мне, что Том Престон-Вернер уже писал о разработке, управляемой Readme, в 2010 году!

1. Например, разработка на основе тестирования, разработка на основе поведения или разработка на основе календаря.

2. Был там, сделал то. (Хотя этот README довольно плохой.)

Спасибо за чтение.