Техническое комментирование

Question

Какие специальные приемы вы используете при модификации существующего кода?

Например: допустим, вы изменяете бизнес-правило внутри метода. Вы помечаете измененный раздел специальными комментариями?

Какие стандарты кодирования / комментирования вы используете при изменении кода?

Answer 1

Вы имеете в виду что-то вроде:

foo();  // changed by SecretWiz, 20090131

Я бы не рекомендовал это. Это загромождает файлы кода, и система контроля версий должна справиться с этим за вас. Он отслеживает, кто что изменил. Используйте

svn blame

Answer 2

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

Answer 3

Одна вещь, которую я всегда пытаюсь сделать, это вставить идентификатор ошибки (или идентификатор запроса функции) в систему отслеживания ошибок в комментариях проверки кода, которые я делаю для этого изменения. Я добавляю что-то вроде «см. Комментарии к этой ошибке / функции в bugzilla для более подробной информации». Там я могу и обычно объясняю причину этого изменения кода. Это означает, что все изменения или, по крайней мере, все важные изменения необходимо отслеживать через запрос функции / идентификатор ошибки. Я много раз создавал ошибку, чтобы подробно объяснить связанные с этим бизнес-причины.

Answer 4

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

// modified by A.B. on 11/23/99 to fix issue #123456

Я видел подобные комментарии в нашей кодовой базе, и они не имеют смысла годами спустя. Кто, черт возьми, А.Б., и что было проблемой # 123456? Если код все еще здесь, значит ли это, что кто-то планирует откатить эти изменения в будущем?

Эти комментарии не имеют значения и служат только для загромождения вашего кода.

Answer 5

Я бы предложил создать метод и вызвать его из кода, который изменяется.
Также назовите метод, чтобы предложить цель / назначение метода.

например. GiveRebateIfValidCoupon();

Answer 6

Я должен согласиться со многими другими людьми здесь, на SO. Msgstr "Если вам не нужно что-то в вашем коде, удалите это". Особенно в производственном коде, последнее, что вы хотите, это много беспорядка. Для кого-то может быть гораздо проще понять, как работает ваше изменение, чем прочитать ваш комментарий по обслуживанию и, возможно, запутаться.

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

Answer 7

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

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

Answer 8

Код должен соответствовать всем стандартам кодирования, которые есть у вас или в вашей организации.

Итак, нет, не должно быть никаких специальных комментариев, что код был изменен - ​​весь или, по крайней мере, большинство, код будет изменен рано или поздно.

Если есть унаследованный вами код, который не соответствует стандартам комментирования, то обязательно добавьте комментарии, как рефакторинг кода. Если код действительно старый и недокументированный, естественно, это означает добавление документации.

Хорошо понять код, прежде чем его модифицировать (кстати).

Answer 9

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

Кроме этого, мы полагаемся на контроль источников.

Answer 10

«Какие стандарты кодирования / комментирования вы используете при изменении кода?»

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

Изменения требований означают добавление подклассов и новых тестов для обработки новых бизнес-правил.