Документирование кода метками

Question

Насколько хорошей практикой является документирование кода метками? В каких ситуациях стоит её использовать?

К примеру, если надо акцентировать внимание в алгоритме:

special_case:
if (cond) {
  ...
  return true;
}
usual_path: 
return false;

Из плюсов:

меньше символов;
можно написать в начале строки перед кодом с более простым синтаксисом, чем /* */.

Из минусов:

только короткие фразы;
предупреждения компиляторов.

Пожалуйста, исправьте вопрос, чтобы он отражал конкретную проблему с достаточным количеством деталей для возможности дать адекватный ответ. — Дух сообщества, Oct 26 '21 at 14:42
О том, что использование goto - плохая практика, написано уже столько... ¿Откуда вообще могла вылезти идея использовать метки для документирования? — user7860670, Oct 26 '21 at 14:43
@user7860670 в вопросе не идёт речь об использовании goto — homebrew, Oct 26 '21 at 14:44
¿т.е. как это, не идет? special_case: - ¿это разве не метка для goto? — user7860670, Oct 26 '21 at 14:45
Как по мне — идея, гм... очень спорная... и это чтоб не выражаться матом :) — Harry, Oct 26 '21 at 14:46
если вместо cond использовать имя is_special_case, то уже метка не нужна. И так далее. Если нужно выделить блок - возможно, этот код нужно вынести в отдельную функцию? Если же и это невозможно - используйте комментарии с метками. Например, //! --- special case ---- — KoVadim, Oct 26 '21 at 14:47
@user7860670 речь идёт об использовании меток как документации кода, а не про использование goto для них — homebrew, Oct 26 '21 at 14:48
А эти метки нельзя просто так использовать без goto. Это будет порождать диагностики при сборке C4102 / Wunused-label — user7860670, Oct 26 '21 at 14:50
@user7860670 добавил в минусы, но этот варнинг можно отключить, если что — homebrew, Oct 26 '21 at 14:52
@user7860670 интересно узнать про сохранение названий меток в бинарях в отличие от комментариев... — homebrew, Oct 26 '21 at 14:53
@KoVadim много символов в //! --- special case ---- по сравнению с меткой — homebrew, Oct 26 '21 at 14:55
ну так Вы же хотите, что бы "оно бросалось в глаза". Но у меток есть большущий минус - Вам нужно будет всем объяснять, зачем это нужно. — KoVadim, Oct 26 '21 at 14:57
Оба ваших плюса сводятся по сути к экономии пары байт. Пара экранирующих символов намного меньше, чем количество символов в самом комментарии и погоды вообще не делает. — user7860670, Oct 26 '21 at 14:59
В некоторых редакторах в самом деле будет выделяться своим другим цветом. Но, уж больно сбивающе для неподготовленного читателя, который может потратить немало времени, выясняя, откуда сюда переходят? — avp, Oct 26 '21 at 18:15
@KoVadim, уверены? А если бинарный файл с DWARF’ом? — 0andriy, Oct 26 '21 at 21:00
Если оставить отладочную информацию, то тут много чего может быть. Тут люди все юмор понимают, но strip для релизов делают — KoVadim, Oct 26 '21 at 21:21

score 2 · Answer 1 · answered Oct 27 '21 at 08:53

Довольно неожиданное предложение по использованию меток и как уже было упомянуто, такое действие будет порождать предупреждения компилятора со всеми вытекающими. Его придётся подавлять, чтобы не отвлекало внимание от других проблем, или вовсе не блокировало сборку при наличии опции "treat warning as an error". Но в таком случае этот тип предупреждений (пусть и редкий в наши дни) можно пропустить в другом коде, где "метки используются как метки, а не альтернатива комментариям".

Вообще, в современном C++ для указания на наиболее вероятную ветвь ветвления стоит использовать атрибуты [[likely]], [[unlikely]]. Атрибуты не только могут быть подспорьем документированию кода, но и дадут подсказку компилятору, чтобы сделать код более эффективным.

if (cond) [[unlikely]] {
  ...
  return true;
}
return false;

Документирование кода метками

1 Answers1