Руководство пользователя для GNU Awk

Приложение C. Замечания о реализации

C.2.1 Добавление новых свойств

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

1. Возьмите последнюю версию. Для меня гораздо легче вставить изменения, если они относятся к самой последней поставляемой версии gawk. Если ваша версия gawk очень стара, я могу оказаться не в состоянии вообще объединить их. См. раздел B.1.1 [Получение поставки gawk], стр. 279, для информации о том, как получить последнюю версию gawk.

2. Следуйте стандартам кодировки GNU. Этот документ показывает, как должно писаться программное обеспечение GNU. Если вы его не читали, прочтите пожалуйста до того, как приступите к модификации gawk. (The GNU Coding Standards доступен как часть Autoconf distribution из FSF.)

3. Используйте стиль кодировка gawk. Cи-код для gawk следует инструкциям в GNU Coding Standards, с минимальными исключениями. Код отформатирован с использованием традиционного стиля "K&R", в особенности в отношении расположения скобок и использования символов tab. Коротко, правила кодирования для gawk таковы:

Используйте старый стиль (non-prototype) заголовков функций при определении функций.

Помещайте имя функции в начале отдельной строки.

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

Описания аргументов функции не должны иметь отступа.

Ставьте пробелы вокруг скобок в управляющих структурах (if, while, for, do, switch и return).

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

Ставьте пробелы вокруг всех Си-операторов и после запятых в вызовах функций.

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

Используйте real tabs для отступов, а не пробелы.

Используйте стиль "K&R" для расположения скобок.

Используйте сравнения с NULL или '"0' в условиях операторов if, while и for, и в случаях операторов switch вместо простых указателей или значений символов.

Употребляйте символьные постоянные TRUE, FALSE и NULL, и символьную константу '"0' где нужно, вместо 1 и 0.

Вставляйте однострочные описательные комментарии для каждой функции.

Не употребляйте `#elif'. Многие старые Unix C компиляторы не умеют их обрабатывать.

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

Если я буду должен переформатировать ваш код в духе, принятом в gawk, я могу не захотеть возиться с ним.

4. Будьте готовы подписать соответствующую статью. Для того, чтобы FSF поставляло ваши изменения, вы должны опубликовать эти изменения, представив подписанный документ такого рода, или передать права на публикацию в FSF. Оба эти действия легко осуществить, и многие авторы это уже сделали. Если у вас есть вопросы, пожалуйста войдите в контакт со мной (см. раздел B.7 [Сообщения о коллизиях и ошибках], стр. 292), или с gnu@gnu.org.

5. Исправьте документацию. Вместе с вашим новым кодом пришлите пожалуйста новые разделы или главы к этой книге. Если возможно, воспользуйтесь Texinfo, вместо представления неформатного текста ASCII (хотя и это лучше, чем совсем никакой документации). Соглашения, которые используются в Эффективном AWK-программировании, помещены после `@bye' в конце Texinfo source file. Если можно, внесите изменения и в справочник man page.

Вы должны будете также подписать письменную статью по вашим изменениям в документации.

6. Согласуйте изменения с context diffs или unified diffs. Используйте `diff -c -r -N' или `diff -u -r -N' для сравнения оригинального дерева gawk с вашей версией. (Я считаю context diffs более удобочитаемым, а unified diffs более компактен.) Рекомендую использовать версию GNU diff. Перешлите мне результаты, выданные каким-нибудь исполнением diff после согласования. См. раздел B.7 [Сообщения о коллизиях и ошибках], стр. 292, об информации по электронной почте. Использование названного формата облегчит мне внесение ваших изменений в эталонную версию исходного кода gawk (установку заплатки). Если я буду должен произвести вставку вручную, используя текстовый редактор, я могу этого не сделать, особенно при наличии множества изменений.

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