Есть ли стандарт для комментариев "???", "!!!", "TODO" и т.д. В комментариях?

Я говорю о специальных словах/токенах, используемых в начале комментариев, чтобы облегчить grepping или иначе придать особое значение комментарию, например // TODO: Find out what to do about this error.

Значение некоторых тегов очевидно, например TODO и FIXME, но как насчет ??? и !!!? Есть ли другие? Я спрашиваю, потому что недавно я видел последние два, и некоторые редакторы, то есть Xcode, предоставляют простой способ найти все комментарии, которые такие теги.

Если нет стандарта как такового, я в порядке с описанием любой локально-местной политики, которую вы могли бы иметь.:)

Изменить: бонусные точки для ссылки на фактический документ.

Ответы

Ответ 2

Краткий ответ: Нет.

Длинный ответ:

  • Глобально и официально? Нет.
  • В глобальном масштабе неофициальный (как используется большинством разработчиков)? Любопытное.
  • Per-IDE? Обычно, да.

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

Реализация таких систем, а также самих токенов по умолчанию имеют широкий диапазон вариантов синтаксиса, количество токенов, определенных по умолчанию, и "имя" токенов. Все зависит от IDE.

"Самый стандартный" токен комментария, безусловно, TODO; почти все IDE, которые реализуют систему токенов комментариев, также определяют по меньшей мере TODO по умолчанию. Другие общие токены: TOFIX или FIXME, BUG и NOTE.

Некоторые примеры этих стандартов на основе IDE:

По умолчанию Visual Studio включает в себя следующие токены: HACK, TODO, UNDONE, NOTE. Они не чувствительны к регистру.

  1. Eclipse: @todo, FIXME, TODO и XXX.

По умолчанию в список включены четыре общие строки.

  1. Netbeans: TODO, FIXME и т.д.

Окно Action Items автоматически сканирует ваш код и отображает прокомментированные строки, содержащие такие слова, как "TODO" или "FIXME", а также строки с ошибками компиляции, быстрыми исправлениями и предупреждениями стиля.

  1. IntelliJ IDEA: не менее TODO.

По умолчанию любая строка, начинающаяся с TODO (независимо от случая), интерпретируется как элемент TODO и подсвечивается соответствующим образом.

  1. Код:: Блоки: По крайней мере TODO.

Если источники открыты в CodeBlocks, Todo может быть добавлен в список через команду Add To-Do из контекстного меню. Комментарий будет добавлен в выбранную строку исходного кода.

// TODO (user#1#): add new dialog for next release

  1. Rider: TODO и BUG по умолчанию, но также косвенно предлагает и объясняет использование REVIEW, NOTE и HACK.

На протяжении многих лет я видел базы кода, которые используют один (или более) из этих типов комментариев для описания задач, которые должны выполняться в какой-то момент, например, как часть "правила мальчика-разведчика":

  • TODO - простой "todo", который должен быть выполнен в какой-то момент (но очень часто остается в кодовой базе в течение многих лет)
  • ОБЗОР - что-то, что должен заметить рецензент кода и комментарий к NOTE - объясняет, почему был написан определенный фрагмент кода и какова основная идея
  • BUG - описывает ошибку (которая, вероятно, также должна быть зарегистрирована в трекере проблем).
  • HACK - объясняет взлом кода

По умолчанию Rider распознает TODO и BUG как комментарии TODO. Чтобы добавить поддержку других комментариев, мы можем определить новый шаблон. Мы можем сделать это из настроек, в разделе "Редактор | TODO.

Бонус:

Если это кого-то интересует, вот стандарт, который я использую...

Теги и синтаксис:

  • @NOTE - обозначает любую заметку о чем-то достаточно важном, чтобы быть примечательной, но это не связано с действием.
  • @todo - указывает на то, что нужно сделать, но это не исправление (может быть, а может и не важно).
  • @TOFIX - Указывает на то, что требуется для исправления (может быть или не быть сломан).
  • @HACK - указывает на быстрое исправление или обходное решение, которое было сделано либо по необходимости, либо по удобству, и это должно быть заменено или улучшено, если это возможно.
  • @DONE - предупреждение о том, что что-то было сделано, как и ожидалось (заменив предыдущие TODO, TOFIX или HACK), или неожиданно (кто-то заметил что-то новое, которое нуждалось в исправлении или могло быть улучшено, и #LikeABoss, просто пошли и DONE он).
    • Это в основном для внутренней (dev-team) документации, уведомлений и/или целей подтверждения, и рекомендуется периодически очищать их постоянное накопление либо по времени (каждые X дней), или на версиях/сборках (каждый X-версии/сборки). Специально в случае, если исходный код проекта является общедоступным, чтобы избежать беспорядка.
  • @UNDO - указывает на то, что было нарушено после изменения, и что (по крайней мере на данный момент) нужно отбросить назад в предыдущую версию.
  • @UNDONE - Указывает на то, что де-факто (уже) откат назад к предыдущей версии по какой-либо причине.
    • Это в основном для внутренней (dev-team) документации, уведомлений и/или целей подтверждения, и рекомендуется периодически очищать их постоянное накопление либо по времени (каждые X дней), или на версиях/сборках (каждый X-версии/сборки). Специально в случае, если исходный код проекта является общедоступным, чтобы избежать беспорядка.
  • @ASAP - указывает на то, что требует внимания или делает A s S oon A s P ossible.
  • @ISSUE - указывает на любую проблему, которая нуждается в внимании или обзоре, возможно, другими, если вы работаете в команде (нуждается в экспертной оценке).
    • Например, у кого-то есть сомнения или вопросы о чем-то; или указание чего-то, где изменение, вероятно, хорошая идея; или фактическая проблема, по которой кто-то неохотно переходит в TODO или TOFIX по какой-либо причине.
      ISSUE - это в основном NOTE, что требует внимания, а не просто примечательно, но что все еще (может или не может быть связано с действием).
  • @GLITCH - указывает на то, где ситуация на входе или потоке программы приводит к странному или неожиданному поведению, но это не нарушает работу программы или выводит данные.
  • @BUG - указывает на то, где ситуация на входе или потоке программы приводит к прямому нарушению программы (замораживание, сбой или другая серьезная проблема) или выход (неспособность выводить или выводить неверные данные).
  • @REVIEW - указывает на то, что нужно пересмотреть.
  • @BENCHMARK - указывает на то, что имеет несколько решений и где разница в накладных расходах не очевидна.
    • Используется непосредственно перед комментарием раздела кода, который должен быть протестирован против используемого в настоящее время кода, который, в свою очередь, помещается непосредственно ниже этого.

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

Например:

  • A TODO, которому нужно выполнить ASAP, будет написано @TODO:ASAP: This [blablabla] needs to be done as soon as possible because [blablabla]!
  • Недостаток GLITCH, который вызывает мерцание компонента GUI всего за несколько миллисекунд, и это происходит только при очень специфических условиях, может быть указано...
    • Как GLITCH; возможно, указывает на низкий приоритет через предопределенный "спецификатор", например @GLITCH:LowPriority: The [blablabla] component flickers for a bit when this function is called with [blablabla] as values.
    • Как ISSUE, а не с неявным более высоким приоритетом тега GLITCH, например @ISSUE:GLITCH: [continues like the example above].

Итак, правила sintax сводятся к простому:

@MAIN_TAG:((SUB_TAG)|@?(Specifier):)* Message

Примеры:

//@TODO: Implement a delta-time loop class to replace this

//@TOFIX:ASAP: Accumulator doesn't have enough precision; change type to double, and deal with the cascading effects throughout the code

//@NOTE: 'lhc' stands for "Large Hadron Collider" in the function/method below

//@ISSUE:Bob:@Scott: This is where I'm missing an '*Exception (...)'; probably a missing import.

//@DONE:Scott: I've sent a copy of the missing lib to Bob, and explained him how to use it. Issue removed

//@ASAP: Replace or add and handle an alternative to the usage of 'BrandNewLanguageFeature' from the code below. We need to support an older version.

Ответ 3

Мы используем Java с Eclipse и, следовательно, теги Eclipse по умолчанию TODO, FIXME и XXX. Я использую XXX, когда что-то действительно не сломано, но очень странно или должно быть сделано по-другому.

Ответ 4

В Visual Studio есть "Список задач", а тегами по умолчанию (на VS2010) являются "HACK", "TODO", "UNDONE" и "UnresolvedMergeConflict". Поэтому я бы рекомендовал использовать их, если вы используете Visual Studio.

Ответ 7

Я использую!!! для кода, который должен быть исправлен до его совершения. Я использую??? для странных/должно быть сделано по-другому/просто не выглядит правильным (всегда с объяснением).

Ответ 9

Что бы вы ни выбрали, убедитесь, что вы придерживаетесь точно. Поэтому, если вы идете с // TODO, убедитесь, что всегда это и никогда //TODO или // TO DO.

Почему?

Если это одна строка, простой поиск найдет все места, где он все еще существует в коде, и вы можете более легко отслеживать их.

В идеале у вас не должно быть никаких - но мы не живем (или работаем) в идеальном мире.

Ответ 10

Нет, хотя TODO более распространен.

Для подробного исследования:

Storey, M.-A., J. Ryall, I. Bull, D. Myers, J. Singer, "TODO или To Bug: исследование того, как аннотации задач играют роль в практике работы разработчиков программного обеспечения", Материалы Международной конференции по разработке программного обеспечения, Лейпциг, Германия, 10-18 мая 2008 г.

Ответ 11

В документе вы по-прежнему хотите ссылаться на документ, "официальное" (Oracle) соглашение Java-кода (http://www.oracle.com/technetwork/java/codeconventions-137265.html#395):

10.5.4 Special Comments

Use XXX in a comment to flag something that is bogus but works. 
Use FIXME to flag something that is bogus and broken.