Comments 13
Спасибо за пост и поздравления! =)
От себя хотел бы добавить исходя из практики — надо добавлять ещё дату в комментарий и кто писал его. Просто пока работал в банке и модули изменяли несколько программистов даже при наличии SVN код потом разбирать сложно было. Удобнее когда каждый соблюдал простое правило, что-то типа:
дата сразу акцентирует внимание когда были внесены изменения в код, и при желании можно обычным поиском найти все изменения за конкретную дату или отследить как и что изменялось
ник позволяет определить кем вносились изменения, что бы потом определиться зачем или с кем идти с вопросами или кулаками =)
От себя хотел бы добавить исходя из практики — надо добавлять ещё дату в комментарий и кто писал его. Просто пока работал в банке и модули изменяли несколько программистов даже при наличии SVN код потом разбирать сложно было. Удобнее когда каждый соблюдал простое правило, что-то типа:
\\ 01.01.2011 Odu изменение инструмента формирования счетов дата сразу акцентирует внимание когда были внесены изменения в код, и при желании можно обычным поиском найти все изменения за конкретную дату или отследить как и что изменялось
ник позволяет определить кем вносились изменения, что бы потом определиться зачем или с кем идти с вопросами или кулаками =)
Еще можно дополнять комментарии номером задачи из таск-трекера. «Для чего тут так сделано» будет намного проще определить. А заодно и кто и когда ))
git/svn annotate
В компании, где работаю принято комментировать еще и замены кода:
// Компания, Сотрудник, Дата
// Замена
// Было
// <Старый код>
// Стало
<Новый код>
Да, этот подход приводит к некоторому нагромождению, но зато достаточно удобно поиском посмотреть все внесенные доработки и при необходимости вернуть все назад.
// Компания, Сотрудник, Дата
// Замена
// Было
// <Старый код>
// Стало
<Новый код>
Да, этот подход приводит к некоторому нагромождению, но зато достаточно удобно поиском посмотреть все внесенные доработки и при необходимости вернуть все назад.
В SVN Blame есть.
В других тоже наверное.Построчно показывает кто автор и ревизию.
В других тоже наверное.Построчно показывает кто автор и ревизию.
Возможно вы где-то имели это ввиду, но я бы добавил еще такой совет:
— В комментарии описывайте не процедурную логику с точки зрения программы, а семантику или бизнес логику.
Врядли это понятно, приведу примеры (слегка утрированные):
«Далее мы перебираем массив такой-то, суммируем поле price у элементов с state=1» — плохо
«Возвращем false если 8-й бит поля User->Rights равен нулю» — плохо
«Далее мы суммируем цены актуальных товаров на складе» — хорошо
«Дальнейшие действия доступны только администратору» — хорошо
Т.е. "что мы тут делаем" чаще всего должно быть понятно из кода (хотя тоже исключения бывают), а вот зачем и почему мы так делаем, хорошо бы написать в комментариях.
— В комментарии описывайте не процедурную логику с точки зрения программы, а семантику или бизнес логику.
Врядли это понятно, приведу примеры (слегка утрированные):
«Далее мы перебираем массив такой-то, суммируем поле price у элементов с state=1» — плохо
«Возвращем false если 8-й бит поля User->Rights равен нулю» — плохо
«Далее мы суммируем цены актуальных товаров на складе» — хорошо
«Дальнейшие действия доступны только администратору» — хорошо
Т.е. "что мы тут делаем" чаще всего должно быть понятно из кода (хотя тоже исключения бывают), а вот зачем и почему мы так делаем, хорошо бы написать в комментариях.
У нас таск-трекер не сразу появился. Потом я, конечно, стал добавлять номер задачи с helpdesk-а
Спасибо за уточнение, кстати, не подумал дописать)
Спасибо за уточнение, кстати, не подумал дописать)
И конечно же следите за кодегайдом своей организации!
Sign up to leave a comment.
Комментирование кода