Правило AUTOSAR C++ 14 A2-7-2

Разделы кода не должны «комментироваться»

Описание

Определение правила

Разделы кода не должны «комментироваться».

Объяснение

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

Кроме того, комментарии в стиле C, содержащиеся в /* */ не поддерживают вложение. Комментарий, начинающийся с /* заканчивается на первом */ даже когда */ представляет собой конец более позднего вложенного комментария. Если раздел кода, который комментируется, уже содержит комментарии, вы можете столкнуться с ошибками компиляции (или, по крайней мере, прокомментировать меньше кода, чем вы предполагаете).

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

Внедрение Polyspace

Средство проверки использует внутреннюю эвристику для обнаружения комментированного кода. Например, такие символы, как #, ;, { или } укажите комментарии, которые потенциально могут содержать код. Эти комментарии затем оцениваются по другим метрикам, чтобы определить вероятность маскировки кода как комментария. Например, несколько последовательных слов без символа между ними уменьшают эту вероятность.

Средство проверки не помечает следующие комментарии, даже если они содержат код:

Комментарии Doxygen начинаются с /**, /*!, /// или //!.
Комментарии, повторяющие один и тот же символ несколько раз, например символ = здесь:
```
// =====================================
// A comment
// =====================================*/
```
Комментарии к первой строке файла.
Комментарии, сочетающие стиль C (/* */) и стиль C++ (//).

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

Поиск неисправностей

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

Примеры

развернуть все

Комментарии к коду с комментариями в стиле C

#include <iostream>
/* class randInt {
    public: 
      int getRandInt();
};
*/

int getRandInt();

/* Function to print random integers*/ 
void printInteger() {
    /* int val = getRandInt(); 
     * val++; 
     * std::cout << val;*/     
    std::cout << getRandInt();
}

Этот пример содержит два блока кода с комментариями, что составляет два нарушения правил.

Комментарии кода с комментариями стиля C++

#include <iostream>
int getRandInt();

// Function to print random integers
void printInteger() {
    // int val = getRandInt(); 
    // val++; 
    // std::cout << val;     
    std::cout << getRandInt();
}

В этом примере содержится блок кода с комментариями, нарушающий правило.

Проверить информацию

Группа: Лексические конвенции

Категория: Обязательные, неавтоматические

См. также

Check AUTOSAR C++ 14 (-autosar-cpp14)

Темы

Проверка нарушений стандартов кодирования

Представлен в R2020b

Документация