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>."

"Данная заплата решает первоочередную проблему, но я понимаю, что она неприятно усложняет распределение памяти. У меня заплата работает, однако перед распространением ее, вероятно, следует протестировать под большой нагрузкой."

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