Есть ли способ отличить информативные комментарии от закомментированного кода?

В процессе программирования вы получите несколько комментариев, объясняющих код, и некоторые комментарии, которые удаляют код:

// A concise description 
const a = Boolean(obj);
//b = false;

Есть ли хороший метод для быстрого анализа, который какой?

Я играл с использованием 3 /-х и /** */для описательных комментариев.

Я также использовал плагин VSCode, чтобы выделить //TODO:и//FIXME:

Существует очень простое решение: удалить закомментированный код.

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

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

# TODO: Replace with `foo = frobnicate(bar)` once <link.to/bug> is fixed
foo = [some complex workaround]

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

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

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

Однако, если вы ищете соглашение о маркировке кода для последующего удаления, мой старый фаворит:

//b = false; //TODO: remove

Некоторые //TODO:комментарии IDE или могут быть научены. Если нет, то обычно это строка для поиска. Лучше всего следовать соглашению, которое установил ваш магазин, потому что это можно сделать несколькими способами. Каждая база кода должна делать это одним способом. Поддерживает поиск

разбор быстро какой есть какой?

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

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

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

Я использую директивы препроцессора для удаления кода, а не комментарии:

//comment
active_code();
#if FALSE
inactive_code();
#endif

Это делает поиск очень простым, и моя подсветка синтаксиса воспринимает это как комментарий. Я даже могу свернуть это в одну строку:#if FALSE(...)

Вы можете расширить эту идею, чтобы иметь несколько вариантов:

#if OPTION == 0
code_for_option_0();
#elif OPTION == 1
code_for_option_1();
#else
code_for_all_other_options();
#endif

И проверка ошибок во время компиляции:

#if FOO >= 5
#error FOO should be less than 5!
#endif

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

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

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

(Моя основа - C #, но это может быть применено к любому языку C-синтаксиса, например Java)

// An explanatory comment has a space between the comment marker and the content.

// The following lines are commented out code so do not have the space (except where indented).
//var a = something();
//if(a==2) {
//   doSomethingElse();
//}

Я все еще интерпретирую вопрос, думая, что вы хотите найти закомментированный код.

Код в стиле C обязательно должен содержать точки с запятой, в то время как комментарий вряд ли содержит точки с запятой. Так что для закомментированного однострочного кода вы можете использовать это регулярное выражение:

\s*\/\/[\s\S]*;

Для многострочного закомментированного кода это может быть

\/\*[^\;]*;[^\;]*\*\/

Примечание. Visual Studio немного отличается от разрывов строк в регулярных выражениях, они не считаются пробелами, вам нужно указать явное \ n.

Если вы используете редактор с работающим в фоновом режиме компилятором (например, Xcode и Clang), вы можете просто попытаться скомпилировать текст комментария. Например, «краткое описание» дает ошибки, «b = false;» - нет. Затем вы можете использовать другую подсветку синтаксиса.

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

В других ответах были варианты «не комментируйте код». Но иногда вы все еще хотите это для справки.

Если вам действительно нужен код, чтобы остаться рядом, лучшим решением будет окружить код "#if 0 ... #endif", в идеале с комментарием, чтобы сказать, почему. Это рекомендуемая стратегия из различных стандартов кодирования, включая MISRA.

Просто, по крайней мере для меня - и в C / C ++. Комментарии в / * * / носят информативный характер. Тестовый код, который временно удален, закомментирован с ведущим //.

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