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

18

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

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

Санхьюн Ли
источник

Ответы:

22

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

Майкл Боргвардт
источник
+1 Это, похоже, относится к комментариям к проблеме jQuery. - Отсутствие комментариев здесь может быть очень запутанным.
Конрад Рудольф
1
Я лично ссылаюсь на проблемы в коде только в том случае, если в коде есть обходной путь для проблемы в стороннем коде. Ссылки на ваш собственный трекер ошибок принадлежат системе контроля версий, а не внутри кода. Для большой базы кода может иметь смысл использовать аналогичные ссылки и для внутренних обходных путей.
Микко Ранталайнен,
14

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

Например:

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

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

Бернард
источник
Я думаю ты прав. Тогда, как вы думаете, почему коммиттеры jQuery помещают номера ошибок в комментарии? Может быть, это особый случай для популярного кода?
Санхьюн Ли
6
Я не согласен. Здесь есть комментарии, чтобы объяснить, почему код такой, какой он есть, когда это не очевидно из самого кода. Ошибки могут дать хороший контекст для «почему» кода, поэтому ссылка на ошибку может быть очень полезна для ее понимания. Сказав , что я делать , как ссылки на билеты ошибки в журналах управления версиями , как хорошо, но это служит другой цели.
Йерун
Я думаю, что вы должны сделать и то и другое, но я не думаю, что этого достаточно, чтобы добавить эти комментарии в контроль исходного кода. Вы редко даже видите эти комментарии, если вы не ищете их. Иметь эти ссылки гораздо более наглядно может быть полезным IMO.
Бенджамин Вуттон
1
Йерун: Я снова не согласен с тобой. То есть, если исправление ошибки является быстрым и уродливым взломом, вы должны прокомментировать это и исправить ошибку. Если это правильное исправление, оно должно объяснить, почему оно так, как есть. В идеальном случае не должно быть никаких причин для комментариев любого рода, и достаточно ссылки на ошибку в управлении исходным кодом. Если ваше исправление не говорит само за себя, вы должны рассмотреть возможность его рефакторинга.
Мартирт
Если бы это была реализация, а не ошибка, вы бы не увидели комментарий. Почему? Поскольку развитие кода является нормальным и даже ожидаемым, поэтому реализация функции не будет ссылаться на ее идентификатор задачи, если только обстоятельства не были особенными, в отличие от исправления ошибок, которое служит для быстрого поиска заметных отличий от оригинала для устранения проблем. В противном случае программист, смотрящий на код, может в течение часа почесать голову, пытаясь понять, почему это было сделано иначе, по сравнению с остальной частью кода (и может изменить его обратно в худшем случае).
Нейл
7

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

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

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

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

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

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

Бенджамин Вуттон
источник
2
Если вы используете какую-то систему кодирования исходного кода / версии, которая стоит того, ваша система контроля версий может анонсировать каждую строку вашего кода ревизией, которая его изменила. Например, по умолчанию git gui blame <filename>предоставляется очень быстрый графический интерфейс для просмотра истории кода, если вы используете git. Использование инструмента для объединения комментариев кода с историей позволяет намного лучше документировать код, чем когда-либо встроенные комментарии. То есть, если вы не хотите писать хорошие коммит-сообщения (хорошее коммит-сообщение должно быть примерно равно почтовому сообщению, объясняющему, почему следует применить этот патч).
Микко Ранталайнен,
Если вы начинаете проект с нуля, используя трекер ошибок, практически все строки кода происходят из пользовательской истории или исправления ошибки, что тогда? Вы комментируете все строки?
ГабриэльОширо,
5

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

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

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

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

S.Robins
источник
4

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

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

Например:

// 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.

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

CodesInChaos
источник
0

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

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

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

Скайлер
источник