Полезно ли комментировать номер вопроса?

Я видел много номеров выпусков из комментариев кода jQuery . (На самом деле в коде jQuery было 69 номеров выпусков.) Я думаю, что это будет хорошей практикой, но я никогда не видел никаких рекомендаций.

Если это хорошая практика, каковы рекомендации для этой практики?

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

Я думаю, что достаточно добавить номер проблемы в сообщение о фиксации, когда вы фиксируете соответствующее исправление в своей системе контроля версий.

Например:

Ошибка № 203: Соединения с базой данных больше не истекают через 30 секунд.

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

Я полностью не согласен с другими постерами здесь!

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

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

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

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

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

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

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

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

Учитывая все это, я бы предположил, что это не очень хорошая практика, так как добавление номеров проблем в комментарии в вашем коде.

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

Я обычно добавляю комментарии, только если в этом фрагменте кода есть что-то неуловимое или неинтуитивное. Так как некоторые тонкие проблемы не могут быть полностью объяснены в нескольких строках, и я не хочу добавлять десятки строк комментариев, я бы добавил короткий комментарий, описывающий то, чего это пытается достичь, и обратился к проблеме для Детали.

Например:

// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details

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

Или:

// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.

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

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

С учетом вышесказанного я не уверен на 100% из комментариев кода. Включение номеров проблем в код хорошо работает, если номера проблем сохраняются (например, вы не меняете средства отслеживания проблем), и у вас не много проблем для данного проекта.

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