Комментирование кода

[Oduvanchik]

Спасибо за пост и поздравления! =)
От себя хотел бы добавить исходя из практики — надо добавлять ещё дату в комментарий и кто писал его. Просто пока работал в банке и модули изменяли несколько программистов даже при наличии SVN код потом разбирать сложно было. Удобнее когда каждый соблюдал простое правило, что-то типа:
\\ 01.01.2011 Odu изменение инструмента формирования счетов
дата сразу акцентирует внимание когда были внесены изменения в код, и при желании можно обычным поиском найти все изменения за конкретную дату или отследить как и что изменялось
ник позволяет определить кем вносились изменения, что бы потом определиться зачем или с кем идти с вопросами или кулаками =)

[step307]

Еще можно дополнять комментарии номером задачи из таск-трекера. «Для чего тут так сделано» будет намного проще определить. А заодно и кто и когда ))

[evilbloodydemon]

git/svn annotate

[skyksandr]

В компании, где работаю принято комментировать еще и замены кода:
// Компания, Сотрудник, Дата
// Замена
// Было
// <Старый код>
// Стало
<Новый код>

Да, этот подход приводит к некоторому нагромождению, но зато достаточно удобно поиском посмотреть все внесенные доработки и при необходимости вернуть все назад.

[Vass]

Для этого придумали системы контроля версий, вы делаете эту работу вручную, ужас, ужас, ужас

[skyksandr]

Да, т.к. работаю с 1С и не все клиенты используют хранилище конфигурации (своего рода система контроля версий).

[Sect0R]

Ужасно конечно.
Такие комментарии 30-50% рабочего времени занимают, а толку от них 5% :(

[workless]

В SVN Blame есть.
В других тоже наверное.Построчно показывает кто автор и ревизию.

[step307]

Возможно вы где-то имели это ввиду, но я бы добавил еще такой совет:

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

Врядли это понятно, приведу примеры (слегка утрированные):

«Далее мы перебираем массив такой-то, суммируем поле price у элементов с state=1» — плохо
«Возвращем false если 8-й бит поля User->Rights равен нулю» — плохо

«Далее мы суммируем цены актуальных товаров на складе» — хорошо
«Дальнейшие действия доступны только администратору» — хорошо

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

[TheShock]

Согласен с идеей, но не согласен с примерами:

«Далее мы суммируем цены актуальных товаров на складе» — плохо

this.countSum( warehouse.getActualItems() ); // хорошо

«Дальнейшие действия доступны только администратору» — плохо

if (user.hasRole( 'admin' )) {
    // хорошо
}

[step307]

Как я сказал, примеры утрированны.

Хороший код, как известно, в комментариях не нуждается. Это продемонстрировали вы ))

[Oduvanchik]

У нас таск-трекер не сразу появился. Потом я, конечно, стал добавлять номер задачи с helpdesk-а
Спасибо за уточнение, кстати, не подумал дописать)

[QtRoS]

И конечно же следите за кодегайдом своей организации!