Искусство программирования для Unix - Эрик Реймонд

Уровни переносимости также упрощают приложения. Программы редко нуждаются в полной функциональности или более сложных системных вызовах, таких как mmap(2) или stat(2), а программисты часто конфигурируют такие сложные интерфейсы неверно. Уровень переносимости с абстрактными интерфейсами (например, функция с именем __file_exists вместо вызова stat(2)) позволяет импортировать из системы только ограниченную, необходимую функциональность, упрощая код приложения.

Рекомендуется всегда писать уровень переносимости на основе функции, а не на основе платформы. Попытки создания отдельных уровней переносимости для каждой поддерживаемой платформы приводят к многочисленным проблемам обновления и обслуживания. "Платформа" всегда выбирается на основе по крайней мере двух параметров: компилятор и версия библиотеки/операционной системы. В некоторых случаях используются три фактора, как когда Linux-поставщики выбирают библиотеку С независимо от версии операционной системы. В случае с M-поставщиками, N-компиляторами и O-версиями операционных систем, количество платформ быстро превышает пределы досягаемости любых коллективов разработчиков, кроме крупнейших. С другой стороны, при использовании стандартов языков и систем, таких как ANSI и POSIX 1003.1, набор функций является относительно ограниченным.

Выбор уровня переносимости можно осуществлять либо по строкам кода, либо по компилированным файлам. Нет различий при выборе альтернативных строк кода на платформе или одного из нескольких различных файлов. Практическое правило заключается в том, чтобы перенести код переносимости для различных платформ в отдельные файлы, когда реализация значительно отличается (распределение общей памяти в Unix и Windows), и оставлять код переносимости в одном файле, когда различия минимальны (например, в зависимости от использования функции gettimeofday, clock_gettime, ftime или time для определения текущего времени суток).

За пределами уровня переносимости необходимо придерживаться следующей рекомендации.

Директивы #ifdef и #if являются последним средством, обычно признаком неудачного воображения, чрезмерной дифференциации продукта, неоправданной "оптимизации" или накопленного мусора. Их использование в середине кода — бедствие. Образцовый пример — /usr/include/stdio.h из GNU.

Использование директив #ifdef и #if допустимо (если хорошо контролируется) внутри уровня переносимости. За его пределами необходимо упорно пытаться заключить их в обусловленные #includes, исходя из символов функций.

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

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

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

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

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

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

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

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

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