Комментарии в C++: однострочные // и многострочные /* */

Зачем нужны комментарии

Комментарий - это текст в вашем исходном коде, который компилятор C++ полностью игнорирует. Он никогда не попадает в скомпилированную программу - он существует исключительно для людей, читающих код. Комментарии нужны, чтобы объяснить, почему что-то сделано определённым образом, оставить напоминания или временно отключить код, не удаляя его.

Опираясь на уже знакомый вам синтаксис C++, комментарии - одна из немногих вещей, которые можно поставить почти где угодно, и компилятор просто их пропустит. В C++ есть два вида: однострочные (//) и многострочные блочные комментарии (/* */).

Однострочные комментарии

Две косые черты (//) начинают комментарий, который тянется до конца текущей строки. Компилятор пропускает всё от // до перевода строки.

#include <iostream>
using namespace std;

int main() {
    // Вывести приветствие в консоль
    cout << "Hello, C++!" << endl;

    int score = 90; // комментарий может стоять и после кода
    cout << score << endl;
    return 0;
}

Обратите внимание, что второй комментарий делит строку с настоящим кодом. Всё, что перед //, по-прежнему выполняется; игнорируется только то, что после него. Это самый распространённый стиль комментариев для коротких заметок.

Многострочные блочные комментарии

Когда заметка занимает несколько строк, блочный комментарий выглядит аккуратнее, чем // перед каждой строкой. Блочный комментарий начинается с /* и заканчивается */. Всё, что между ними - сколько бы строк это ни было - игнорируется.

#include <iostream>
using namespace std;

int main() {
    /*
     * Эта программа показывает блочный комментарий.
     * Звёздочки в начале каждой строки - всего лишь
     * соглашение для читаемости, они не обязательны.
     */
    cout << "Block comments are handy." << endl;
    return 0;
}

Выровненные по краю символы * - это соглашение об оформлении, а не правило. Единственное, что действительно важно, - это открывающие /* и закрывающие */. Блочный комментарий может даже находиться посреди строки - int x = 5 /* width */ + 2; корректен, - хотя такое быстро становится трудночитаемым.

Как закомментировать код

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

#include <iostream>
using namespace std;

int main() {
    cout << "This line runs." << endl;

    // cout << "This line is disabled." << endl;

    /*
    cout << "So is this one," << endl;
    cout << "and this one too." << endl;
    */

    cout << "This line runs as well." << endl;
    return 0;
}

Запустите программу, и вы увидите, что выводятся только две строки «runs». Закомментированные инструкции cout невидимы для компилятора.

Подвох с отсутствием вложенности

Ловушка, в которую попадают новички: блочные комментарии не вкладываются. Первый же */ закрывает комментарий, сколько бы /* ни шло перед ним. Поэтому нельзя обернуть блок /* ... */ внутрь другого блока /* ... */ - внутренний */ завершает всё, и то, что идёт после него, снова становится кодом (обычно это синтаксическая ошибка).

/*  Trying to disable a region that already has a block comment...
    int n = 10; /* the width */
    cout << n;
*/  // the first */ above already closed the comment - this line is now stray code

Внешний комментарий заканчивается на */ после the width, поэтому остальное больше не закомментировано, и компилятор спотыкается на завершающем */. Когда нужно отключить участок, который уже содержит блочные комментарии, используйте // в каждой строке. Большинство редакторов переключают строчные комментарии для всего выделения одним сочетанием клавиш, что полностью обходит эту проблему.

Хорошие комментарии против шума

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

// Bad: just repeats what the code obviously does
i = i + 1; // add one to i

// Better: explains the reason, which the code can't show
retries++; // back off and retry; the API is rate-limited at 5 req/sec

Стремитесь сделать код читаемым за счёт понятных имён и структуры, а комментарии приберегите для почему: намерение, компромиссы, граничные случаи и ссылки на контекст. Если вы ловите себя на том, что пишете комментарий, чтобы объяснить запутанную строку, это часто намёк на то, что лучше переименовать переменную или вынести логику в функцию с понятным именем.

Далее: Переменные

Теперь, когда вы умеете снабжать код пояснениями, следующий строительный блок - хранение в нём данных. Следующая страница посвящена переменным: как их объявлять, какие встроенные типы они хранят и какие правила навязывает C++, будучи языком со статической типизацией.