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

Реймонд Эрик Стивен

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

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

и чистота кода имеют наивысший приоритет. Подробности стандарта кодирования второстепенны.

19.2.4. Хорошая практика создания дистрибутивов

Приведенные ниже рекомендации описывают, как должен выглядеть дистрибутив, когда пользователь загружает, восстанавливает и распаковывает его.

19.2.4.1. Убедитесь, что архивы всегда распаковываются в один новый каталог

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

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

fоо-0.23.tar.gz

распаковывается в подкаталог

fоо-0.23

.

В примере 19.1 демонстрируется решение для make-файла, которое позволяет реализовать указанный принцип в предположении, что каталог дистрибутива называется "foobar", a SRC содержит список файлов дистрибутива.

Пример 19.1. make-правила для tar-архива

foobar-$(VERS) .tar.gz:

 @ls $(SRC) | sed s:^:foobar-$(VERS)/: >MANIFEST

 @(cd ..; ln -s foobar foobar-$(VERS))

 (cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar /MANIFEST`)

 @(cd ..; rm foobar-$(VERS))

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

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

19.2.4.3. Придерживайтесь стандартной практики именования файлов

Еще до просмотра

README

– файла бесстрашный исследователь внимательно изучит имена файлов в корневом каталоге распакованного дистрибутива. Имена файлов в нем сами по себе способны нести полезную информацию. Соблюдая определенные стандартные принципы наименования, разработчик может дать исследователю ценную подсказку о том, "куда смотреть дальше".

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

README

Файл-путеводитель, который прочитывают первым.

INSTALL

Инструкции по конфигурированию, компиляции и установке.

AUTHORS

Перечень участников проекта (GNU-соглашение).

NEWS

Последние новости проекта.

HISTORY

История проекта.

CHANGES

Перечень значительных изменений между различными редакциями.

COPYING

Лицензионные условия проекта (GNU-соглашение).

LICENSE

Лицензионные условия проекта.

FAQ

Текстовый документ с перечнем часто задаваемых вопросов по проекту.

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

README

было давно разработано Фондом свободного программного обеспечения.

Наличие файла

FAQ

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

Весьма ценным является наличие файлов

HISTORY

или

ы

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