SonarQube покрытие кода комментариями: как метрика работает на практике и что с ней не так

На одном проекте мы как-то спорили с тимлидом. Он требовал минимум 30% покрытия кода комментариями — SonarQube показывал 12%, и его это бесило. Я открыл топовый файл с 70% покрытия. Там было вот что:

// Increment counter
counter++;

// Check if valid
if (isValid) {
    // Process data
    processData();
}

Комментарии ради комментариев. Пользы — ноль. SonarQube доволен, разработчик нет.

Что SonarQube вообще считает покрытием комментариями

SonarQube анализирует несколько типов комментариев:

Строковые комментарии — однострочные // и многострочные /* */. Это то, что разработчики пишут прямо в коде.

Документирующие комментарии — Javadoc для Java, docstrings для Python, JSDoc для JavaScript. SonarQube выделяет их отдельно, потому что они структурно важнее.

Комментированный код — и вот тут интересно. SonarQube помечает закомментированные блоки как code smell. Это не считается покрытием, это считается долгом.

Метрика работает просто: берётся отношение количества строк с комментариями к общему количеству строк кода. Формула примитивная, но это SonarQube — тут всё довольно прямолинейно.

Какие метрики SonarQube показывает

В интерфейсе вы увидите:

• Comment density — процент покрытия комментариями
• Comment lines — абсолютное число строк с комментариями
• Undocumented API — публичные методы и классы без документации
• Commented-out code — блоки закомментированного кода

По умолчанию SonarQube требует минимум 25% плотности комментариев. Можно настроить в Quality Gate:

# sonarqube-qualitygate.yaml
QualityGate:
  conditions:
    - metric: comment_lines_density
      operator: GREATER_THAN
      value: 25

Но тут нюанс. 25% — это цифра с потолка. Для одного проекта мало, для другого — перебор.

Проблемы метрики

Начну с главного. SonarQube не понимает смысл комментариев. Он считает строки.

Хороший комментарий:

# Using Newton's method for sqrt because standard math.sqrt
# fails on extremely large numbers in this legacy system
def calculate_root(n):

Плохой комментарий:

# Calculate root
def calculate_root(n):

Для SonarQube оба — один комментарий. Одинаково полезны с точки зрения метрики.

Вторая проблема. SonarQube не отличает полезные комментарии от шума. Я видел проекты, где разработчики писали генераторы doc-комментариев только чтобы закрыть метрику. Результат:

/**
 * Process data.
 * @param data The data.
 * @return The result.
 */
function processData(data) {
    return data;
}

Три строки документации, которые ничего не объясняют. SonarQube доволен.

Когда метрика реально полезна

Справедливости ради, есть сценарии где покрытие комментариями помогает.

Публичные API и библиотеки. Если ваш код используют другие команды или внешние разработчики — документация обязательна. Javadoc, docstrings, примеры использования. SonarQube тут работает как минимум как напоминание.

Onboarding новых разработчиков. На проекте с хорошим покрытием комментариев новичку проще. Но только если комментарии содержательные.

Legacy-код. Когда разбираешь старый проект, любой комментарий — уже помощь. Даже банальный "это костыль для синхронизации с SAP".

Настройка SonarQube для проверки комментариев

Если решили использовать, настройте под свой проект. Базовая конфигурация:

# sonar-project.properties
sonar.projectKey=my-project
sonar.sources=src
sonar.exclusions=**/test/**,**/generated/**
sonar.comment_density.min=20

Можно настроить правила для разных типов файлов. Java требует Javadoc для публичных методов. Python — docstrings для функций. JavaScript — JSDoc для экспортируемых сущностей.

Пример исключения из анализа:

<!-- pom.xml для Maven проектов -->
<sonar.exclusions>
  **/dto/**,
  **/generated/**,
  **/config/**
</sonar.exclusions>

DTO и конфиги обычно не нужно комментировать. SonarQube продолжит их считать, но вы хотя бы не будете получать ложные срабатывания на autogenerated код.

Сравнение подходов к проверке комментариев

Честно? Ни один подход не идеален. SonarQube даёт метрику, но не качество. Ручное review даёт качество, но не масштабируется. AI где-то посередине.

Альтернативы SonarQube

Если вам не нравится как SonarQube работает с комментариями, есть варианты.

CodeClimate — похожий подход, но легче. Меньше метрик, проще setup. Для комментариев есть правило "functions without documentation".

ESLint с плагинами — для JavaScript/TypeScript можно настроить require-jsdoc и valid-jsdoc. Работает локально, без сервера:

// .eslintrc.js
module.exports = {
  rules: {
    'require-jsdoc': ['error', {
      require: {
        FunctionDeclaration: true,
        MethodDefinition: true,
        ClassDeclaration: true
      }
    }]
  }
};

AI-боты для code review — анализируют код на отсутствие комментариев там, где они нужны. Не считают строки, а смотрят на контекст. Оставляют инлайн-комментарии прямо в MR.

Как мы решали проблему на том проекте

Вернусь к истории из начала. Мы в итоге договорились так:

1. Снизили порог SonarQube до 15%. Это реалистичная цифра.
2. Договорились о правилах: комментарии только там, где неочевидна логика.
3. Добавили ручное code review с чеклистом: "понятно ли что делает этот метод без комментариев".
4. Для публичного API ввели обязательные docstrings — это требовало бизнес.

Результат: SonarQube перестал быть раздражителем. Код стал чище. Команда happier.

Что с Distiq

Когда мы тестировали Distiq на своих проектах, я заметил разницу с SonarQube. Distiq не считает строки. Он смотрит на код и говорит: "тут непонятно что происходит, добавь комментарий". Или наоборот: "этот комментарий дублирует название функции, удали".

Это другой подход. SonarQube — метрики. Distiq — смыслы. Для команды из 3-5 разработчиков Distiq часто практичнее. Не нужен отдельный сервер, интеграция через webhook за пару минут, комментарии приходят прямо в Merge Request.

Российский сервис, серверы в РФ. Если работаёте с госсектором или критичными данными — это аргумент. Для нас был.