Комментирование обслуживания

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

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

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

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

Answer 7

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

В остальном мы полагаемся на систему контроля версий.

Answer 8

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

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

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

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

Answer 9

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

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

Answer 10

Я должен согласиться со многими другими людьми здесь, на SO.«Если вам что-то не нужно в вашем коде, удалите это».Последнее, что вам нужно, — это беспорядок, особенно в рабочем коде.Кому-то может быть гораздо проще понять, как работает ваше изменение, чем читать комментарии по техническому обслуживанию и, возможно, запутаться.

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