Книга: Искусство программирования для Unix

19.2.4.2. Включайте в дистрибутив README-файл

19.2.4.2. Включайте в дистрибутив README-файл

В дистрибутив программы следует включать файл README, который является путеводителем по дистрибутиву. Согласно давнему соглашению (созданному самим Деннисом Ритчи до 1980 года, и распространенному в Usenet в начале 1980-х годов), данный файл является первым файлом, который будут читать бесстрашные исследователи, после того как распакуют исходный код.

README-файлы должны быть короткими и легко читаемыми. Они должны быть вводным документом, а не крупным произведением. Рассмотрим пункты, которые рекомендуется включать в README-файлы.

1. Краткое описание проекта.

2. Ссылка на Web-сайт проекта (если он существует).

3. Примечания по среде разработки и потенциальным проблемам переносимости.

4. Схема проекта, описывающая важные файлы и подкаталоги.

5. Инструкции по компиляции/установке или ссылка на файл, содержащий такие инструкции (обычно INSTALL).

6. Список кураторов/благодарностей или ссылка на содержащий его файл (обычно CREDITS).

7. Последние новости проекта или ссылка на содержащий их файл (обычно NEWS).

8. Адреса списков рассылки проекта.

В свое время данный файл обычно назывался READ.ME, однако с таким именем плохо взаимодействуют браузеры, которые слишком склонны интерпретировать файл с суффиксом .ME как нетекстовый и позволяют только загружать его, а не просматривать. Такой подход устарел и уже не рекомендуется.

Оглавление книги