19.2.1.8. Включайте в код полезные комментарии

19.2.1.8. Включайте в код полезные комментарии

Куратор хочет иметь полную уверенность в том, что понимает вносимые заплатой изменения, прежде чем объединить их с основным кодом. Данное правило не является неизменным. Если создатель заплаты имеет стаж хорошей работы с куратором, то куратор может только бегло просмотреть изменения перед их почти автоматическим применением. Но все, что можно сделать, чтобы помочь ему понять код и уменьшить неуверенность, увеличивает вероятность того, что заплата будет принята.

Хорошие комментарии в коде помогают куратору понять его, а плохие мешают.

Ниже приводится пример плохого комментария.

/* норман ньюби исправил этот код 13 августа 2001 года */

Данный комментарий не несет в себе никакой информации — просто помарка в центре кода куратора. Если куратор примет данную заплату (что вряд ли), то почти гарантированно удалит данный комментарий. Если разработчик хочет добиться доверия, то ему следует включить диапазон исправлений для таких файлов проекта, как NEWS или HISTORY. В таком случае принятие заплаты куратором более вероятно. Ниже приведен пример хорошего комментария.

/*

* Необходимо защитить этот переход, так чтобы в crunch_data()

* никогда не передавался NULL-указатель.

 <norman_newbie@foosite.com>

*/

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