Чи існує метод відмежування інформативних коментарів від коментованого коду?

Протягом усього програмування ви закінчите кілька коментарів, що пояснюють код, та деякі коментарі, які видаляють код:

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

Деякі прапорці IDE //TODO:коментують або до яких можна навчитись. Якщо ні, то це зазвичай рядок, який можна шукати. Найкраще дотримуватися будь-якої конвенції, яку встановив ваш магазин, оскільки це можна зробити декількома способами. Кожна база коду повинна робити це в один спосіб. Тримає його в пошуку.

швидкий розбір, який є?

Без цього позначки автоматизований спосіб зробити це за допомогою компілятора. Якщо відключення коментаря створює код, який компілюється, він повинен бути коментованим кодом. Написання плагіна 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();
//}

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

Код у стилі С повинен містити напівколонки, хоча коментар навряд чи матиме напівколонки. Отже, для коментованого коду з одного рядка ви можете використовувати цей регулярний вираз:

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

Для коду, що коментується багато рядків, це може бути

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

Примітка: Visual Studio трохи властивий щодо розривів рядків у регулярних виразах, вони не враховуються як пробіли, вам потрібно вказати явний \ n.

Якщо ви використовуєте редактор із компілятором, який працює у фоновому режимі (наприклад, Xcode та Clang), ви можете просто спробувати скласти текст коментаря. Наприклад, "стислий опис" дає помилки, "b = false;" не означає. Потім можна використовувати різні підсвічування синтаксису.

Більш простим методом буде плагін IDE, який використовує деякі евристики, як-от кілька слів підряд, окрім ключових слів, вказує на коментарі, збігається з фігурною точкою з кодом тощо.

Інші відповіді охоплюють варіанти теми "не коментувати код". Але іноді ти все-таки хочеш це зробити для довідок.

Якщо вам справді потрібен код, щоб залишатись навколо, краще рішення - оточити його кодом "#if 0 ... #endif", в ідеалі з коментарем, щоб сказати, чому. Це рекомендована стратегія з різних стандартів кодування, включаючи MISRA.

Просте, принаймні для мене - і в C / C ++. Коментарі, додані до / * * /, є інформативними. Тимчасово видалений код тесту коментується //

І є вагомі підстави залишити тестовий код у файлі, але прокоментував його, принаймні, у такій роботі, яку я виконую. Рано чи пізно хтось захоче внести зміни, які знадобляться цьому коду. Коментування блоку вимагає однієї команди редактора, як і повторне коментування його там, де ви закінчили.