Разделы кода не следует «комментировать»
Разделы кода не следует «комментировать».
С комментарии, содержащиеся в /* */ не поддерживают вложение. Комментарий, начинающийся с /* заканчивается на первом */ даже когда */ представляет собой конец более позднего вложенного комментария. Если раздел кода, который комментируется, уже содержит комментарии, вы можете столкнуться с ошибками компиляции (или, по крайней мере, прокомментировать меньше кода, чем вы предполагаете).
Комментирование кодекса не является хорошей практикой. Код с комментариями может не синхронизироваться с окружающим кодом, не вызывая ошибок компиляции. Позже, если вы раскомментируете код, вы можете столкнуться с неожиданными проблемами.
Используйте комментарии только для пояснения аспектов кода, которые не очевидны из самого кода.
Средство проверки использует внутреннюю эвристику для обнаружения комментированного кода. Например, такие символы, как #, ;, { или } укажите комментарии, которые потенциально могут содержать код. Эти комментарии затем оцениваются по другим метрикам, чтобы определить вероятность маскировки кода как комментария. Например, несколько последовательных слов без символа между ними уменьшают эту вероятность.
Средство проверки не помечает следующие комментарии, даже если они содержат код:
Комментарии Doxygen начинаются с /**, /*!, /// или //!.
Комментарии, повторяющие один и тот же символ несколько раз, например символ = здесь:
/* ===================================== * A comment * =====================================*/
Комментарии к первой строке файла.
Комментарии, сочетающие стиль C (/* */) и стиль C++ (//).
Контролер считает, что эти замечания предназначены для целей документирования или введены намеренно с некоторой предубежденностью.
Если вы ожидаете нарушения правила, но не видите его, обратитесь к разделу Нарушения стандартов кодирования не отображаются.
| Группа: Дизайн кода |
| Категория: Консультационные услуги |
| СМЖЛ Категория: Консультативные услуги |