Стоит ли комментировать изменения в коде и в журнале изменений?

Question

Я заметил, что разработчики склонны меньше комментировать свои изменения с обоснованием того, что цель / дата / причина есть в списке изменений. У них есть несколько очень оправданных утверждений, что дублирование усилий происходит, если нам требуется и то и другое. Я трачу некоторое серьезное время на отслеживание изменений. Никаких конкретных указаний не было дано, и отсутствие последовательного подхода меня немного раздражает. Обычно люди делают оба? Есть ли инструменты, которые я хотел бы попробовать, чтобы сократить время простоя? В настоящее время у нас есть реализации cvs, git и svn.

Answer 1

Комментарии в коде должны описывать , что код в настоящее время делает . Эти комментарии будут меняться только в том случае, если предполагаемое поведение кода изменится - если ревизия является просто исправлением ошибки, они не должны изменяться.

Комментарии в журнале изменений должны описывать какие изменения были внесены в эту ревизию .

Следствие: не указывайте номера / даты ревизий и имена программиста, который внес изменения в комментарии к коду. (Спасибо обоим Джонатанам.)

Answer 2

Не загромождайте свой код комментариями, объясняющими изменения. Это еще одна вещь, которую необходимо поддерживать и, вероятно, не будет постоянно, что приведет к большему количеству ошибок и большему количеству изменений. Используйте функцию комментария управления источником для того, для чего она предназначена.

Если вам нужно , чтобы объяснить, почему что-то было сделано определенным образом в комментариях в вашем коде, это нормально. Пока это не требуется для каждого изменения. Это приводит к беспорядочным комментариям типа

// fixed bug #3365

Answer 3

Оба сервера комментариев различного назначения. Комментарии к коду должны проиллюстрировать и объяснить, что делает фрагмент кода, как он работает, что он ожидает и что он возвращает. Также исключительные условия, которые могут возникнуть.

Комментарии к регистрации больше для того, чтобы сообщить, какие изменения вы сделали, и причины изменения.

Answer 4

Не по моему мнению. Код должен быть прокомментирован так, чтобы вы могли легко прочитать код. Это еще более необходимо для кода, в котором была исправлена ​​ошибка.

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

Они должны делать то и другое и понимать, почему это важно.

Answer 5

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

Answer 6

Не знаю, используете ли вы инструменты аннотаций, некоторые IDE, такие как eclipse, хорошо интегрируются с CVS и показывают, какая именно строка была изменена, когда и кем, если вы используете инструмент аннотаций cvs.