Книга: Искусство программирования для Unix
19.2.1.7. Сопровождайте заплату пояснениями
19.2.1.7. Сопровождайте заплату пояснениями
Заплата должна включать в себя пояснительную записку, объясняющую необходимость или практическую пользу заплаты с точки зрения ее создателя. Данное пояснение адресовано не пользователям программного обеспечения, а его куратору, принимающему заплату.
Записка может быть краткой, фактически некоторые из наиболее эффективных пояснительных записок, которые встречались автору, содержали в себе только одну мысль: "См. обновления документации в данной заплате". Однако записка должна демонстрировать правильное отношение к работе.
Правильное отношение полезно, оно демонстрирует уважение к времени куратора; подобные записки весьма конфиденциальны, но непритязательны. Правильно будет показать понимание исправляемого кода, а также то, что создатель заплаты способен разделить проблемы куратора. Также хорошо закончить упоминанием о любых осознаваемых рисках, связанных с применением заплаты. Ниже приводится несколько примеров пояснительных комментариев, которые отправляют опытные разработчики.
"Я обнаружил в коде две проблемы, X и Y. Проблему X я решил, а проблему Y даже не пытался рассматривать, поскольку не думаю, что понимаю ту часть кода, которая, как я полагаю, с ней связана."
"Исправил ошибки по дампу, которые могут возникать, когда какой-либо foo-ввод является слишком длинным. В ходе решения проблемы я искал подобные переполнения в других местах. Возможная причина переполнения находится в файле blarg.c, где-то около строки 666. Вы уверены, что отправитель не может сгенерировать более 80 символов в течение одной передачи?"
"Вы рассматривали использование Foonly-алгоритма для решения данной проблемы? Здесь есть пример хорошей реализации — <http://www.example.com/~jsmith/foonly.html>."
"Данная заплата решает первоочередную проблему, но я понимаю, что она неприятно усложняет распределение памяти. У меня заплата работает, однако перед распространением ее, вероятно, следует протестировать под большой нагрузкой."
"Возможно, это — украшательство, но я в любом случае его отправляю. Может быть, вам известен более четкий способ реализации данной функции".
- 19.2.1.1. Отправляйте заплаты, а не целые архивы или файлы
- 19.2.1.2. Отправляйте исправления к текущей версии кода
- 19.2.1.3. Не следует включать заплаты для генерируемых файлов
- 19.2.1.4. Не отправляйте заплат, которые только убирают $-идентификаторы систем RCS или SCCS
- 19.2.1.5. Используйте вместо формата по умолчанию (-e) форматы -с или -u
- 19.2.1.6. Сопровождайте заплаты документацией
- 19.2.1.7. Сопровождайте заплату пояснениями
- 19.2.1.8. Включайте в код полезные комментарии
- 19.2.1.9. Не огорчайтесь, если заплата отклонена
- 19.2.1.6. Сопровождайте заплаты документацией
- Совет 32. Сопровождайте вызовы remove-подобных алгоритмов вызовом erase
- Когда длинный документ невозможно сократить, сопровождайте его выжимкой (executive summary)
- Сопровождайте поля форм пояснениями
- 19.2.1. Хорошая практика обмена исправлениями
- 19.2.1.9. Не огорчайтесь, если заплата отклонена