Искусство программирования для Unix
Шрифт:
Записка может быть краткой, фактически некоторые из наиболее эффективных пояснительных записок, которые встречались автору, содержали в себе только одну мысль: "См. обновления документации в данной заплате". Однако записка должна демонстрировать правильное отношение к работе.
Правильное отношение полезно, оно демонстрирует уважение к времени куратора; подобные записки весьма конфиденциальны, но непритязательны. Правильно будет показать понимание исправляемого кода, а также то, что создатель заплаты способен разделить проблемы куратора. Также хорошо закончить упоминанием о любых осознаваемых рисках,
"Я обнаружил в коде две проблемы, X и Y. Проблему X я решил, а проблему Y даже не пытался рассматривать, поскольку не думаю, что понимаю ту часть кода, которая, как я полагаю, с ней связана."
"Исправил ошибки по дампу, которые могут возникать, когда какой-либо foo-ввод является слишком длинным. В ходе решения проблемы я искал подобные переполнения в других местах. Возможная причина переполнения находится в файле blarg.c, где-то около строки 666. Вы уверены, что отправитель не может сгенерировать более 80 символов в течение одной передачи?"
"Вы рассматривали использование Foonly-алгоритма для решения данной проблемы? Здесь есть пример хорошей реализации — <http://www.example.com/~jsmith/foonly.html>."
"Данная заплата решает первоочередную проблему, но я понимаю, что она неприятно усложняет распределение памяти. У меня заплата работает, однако перед распространением ее, вероятно, следует протестировать под большой нагрузкой."
"Возможно, это — украшательство, но я в любом случае его отправляю. Может быть, вам известен более четкий способ реализации данной функции".
19.2.1.8. Включайте в код полезные комментарии
Куратор хочет иметь полную уверенность в том, что понимает вносимые заплатой изменения, прежде чем объединить их с основным кодом. Данное правило не является неизменным. Если создатель заплаты имеет стаж хорошей работы с куратором, то куратор может только бегло просмотреть изменения перед их почти автоматическим применением. Но все, что можно сделать, чтобы помочь ему понять код и уменьшить неуверенность, увеличивает вероятность того, что заплата будет принята.
Хорошие комментарии в коде помогают куратору понять его, а плохие мешают.
Ниже приводится пример плохого комментария.
Данный комментарий не несет в себе никакой информации — просто помарка в центре кода куратора. Если куратор примет данную заплату (что вряд ли), то почти гарантированно удалит данный комментарий. Если разработчик хочет добиться доверия, то ему следует включить диапазон исправлений для таких файлов проекта, как
Данный комментарий
19.2.1.9. Не огорчайтесь, если заплата отклонена
Существует множество причин отклонения заплат, которые никак не связаны с их создателями. Нельзя забывать, что большинство кураторов крайне ограничены во времени и должны быть консервативными в вопросе приема заплат, чтобы не нарушить код проекта. Иногда повторная подача с уточнениями помогает, иногда нет. Такова жизнь.
19.2.2. Хорошая практика наименования проектов и архивов
По мере роста нагрузки на кураторов архивов, подобных ibiblio, SourceForge и CPAN, возрастает тенденция к обработке заявок частично или полностью программным путем (вместо полной их проверки вручную).
В связи с этим возрастает важность подчинения имен проектов и архивов обычным шаблонам, которые могут анализироваться и распознаваться программами.
19.2.2.1. Используйте GNU-стиль названий с именной частью и номерами (основной.второстепенный.заплата)
Будет хорошо, если архивные файлы проекта будут иметь GNU-подобные названия — именной префикс, состоящий из строчных алфавитно-цифровых символов, дефис, номер версии, расширение и другие суффиксы.
Хорошая общая форма названия содержит следующие части в указанном порядке.
1. Префикс проекта.
2. Дефис.
3. Номер версии.
4. Точка.
5. "src" или "bin" (не обязательно).
6. Точка или дефис (точка предпочтительнее).
7. Тип бинарных файлов и параметры (не обязательно).
8. Расширения архивирования и компрессии.
Именная часть в данном стиле может содержать дефис или подчеркивание для разделения составляющих слов; в настоящее время использование дефисов предпочтительнее. Хорошей практикой является группировка связанных проектов путем включения в именные части общего префикса, ограниченного дефисом.
Предположим, существует проект, который называется "foobar", основной номер версии (major version) 1, второстепенный номер версии (minor version) или выпуска 2, уровень исправлений (patchlevel) 3. Ниже представлены примеры названий для проекта, содержащего только один архив (предположительно исходный код).
Архив исходного кода.
LSM-файл (для публикации в ibiblio).
Не следует использовать имена, подобные приведенным ниже.
Многие программы распознают такое имя как архив для проекта, который называется "foobar123" без номера версии.
Многие программы распознают такое имя как архив для проекта, который называется "foobar1" версии 2.3.