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

Примечание автора

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

Если вы хотите скомпилировать фрагмент кода, вам нужно превратить его в полную программу, чтобы она могла скомпилироваться. Обычно эта программа будет выглядеть примерно так:

#include int main() < // Замените эту строку фрагментом кода, который вы хотите скомпилировать return 0; >

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

Пары символов /* и */ отмечают многострочный комментарий в стиле C. Всё, что находится между этими символами, игнорируется.

/* Это многострочный комментарий. Эта строка будет проигнорирована. И эта тоже. */

Поскольку всё, что находится между этими символами, игнорируется, вы иногда можете увидеть, как программисты «украшают» свои многострочные комментарии:

/* Это многострочный комментарий. * выровненные звездочки слева * могут облегчить чтение */

Комментарии в многострочном стиле не могут быть вложенными. Следовательно, результаты следующего кода могут быть неожиданными:

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

Когда компилятор попытается скомпилировать этот код, он проигнорирует все, от первого /* до первого */ . Поскольку фрагмент « это не внутри комментария */ » не считается частью комментария, компилятор попытается скомпилировать его. Это неизбежно приведет к ошибке компиляции.

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

Предупреждение

Не используйте многострочные комментарии внутри других многострочных комментариев. Обертывание однострочных комментариев внутри многострочных комментариев допускается.

Правильное использование комментариев

Обычно комментарии используются для трех вещей. Во-первых, для заданной библиотеки, программы или функции комментарии лучше всего использовать для описания того, что делает библиотека, программа или функция. Обычно они размещаются в верхней части файла или библиотеки или непосредственно перед функцией. Например:

// Эта программа вычисляет итоговую оценку учащегося на основе результатов теста и домашних заданий.

// Эта функция использует метод Ньютона для аппроксимации корня данного уравнения.

// Следующие строки генерируют случайный элемент в зависимости от редкости, уровня и весового коэффициента.

Все эти комментарии дают читателю хорошее представление о том, что пытается выполнить библиотека, программа или функция, не обращая внимания на реальный код. Пользователь (возможно, кто-то другой или вы, если вы пытаетесь повторно использовать код, который вы написали ранее) может сразу определить, соответствует ли код тому, что он или она пытается выполнить. Это особенно важно при работе в команде, где не все знакомы со всем кодом.

Во-вторых, внутри библиотеки, программы или функции, описанной выше, можно использовать комментарии, чтобы описать, как код будет достигать своей цели.

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

// Чтобы сгенерировать случайный элемент, мы сделаем следующее: // 1) помещаем все элементы необходимой редкости в список; // 2) рассчитываем вероятность для каждого элемента на основе уровня и весового коэффициента; // 3) выбираем случайное число; // 4) выясняем, какому элементу соответствует это случайное число; // 5) возвращаем соответствующий элемент.

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

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

Вот несколько примеров плохих комментариев к строке и хороших комментариев к инструкции.

// Устанавливаем дальность прицела на 0 sight = 0;

Причина: мы уже видим, что прицел (sight) устанавливается на 0, посмотрев на инструкцию.

// Игрок только что выпил зелье слепоты и ничего не видит sight = 0;

Причина: теперь мы знаем, почему прицел игрока установлен на 0.

// Рассчитываем стоимость предметов cost = quantity * 2 * storePrice;

Причина: мы видим, что это расчет стоимости, но почему количество умножается на 2?

// Здесь нам нужно умножить количество на 2, потому что они покупаются парами cost = quantity * 2 * storePrice;

Причина: Теперь мы знаем, почему эта формула имеет смысл.

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

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

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

Наконец, комментарии должны быть написаны таким образом, чтобы иметь смысл для тех, кто не знает, что делает код. Часто программист говорит: «Совершенно очевидно, что он делает! Я ни за что не забуду об этом,». Угадайте, что? Это не очевидно, и вы удивитесь, как быстро вы забудете. 🙂 Вы (или кто-то другой) поблагодарите вас позже за то, что вы написали, что, как и почему делается в вашем коде на человеческом языке. Читать отдельные строки кода легко. Понимание того, для чего они предназначены, – нет.

Лучшая практика

Обильно комментируйте свой код и пишите свои комментарии, как если бы разговаривали с кем-то, кто не знает, что делает код. Не думайте, что вы вспомните, почему вы сделали конкретный выбор.

Примечание автора

На протяжении всей остальной части этой серии руководств мы будем использовать комментарии внутри фрагментов кода, чтобы привлечь ваше внимание к конкретным вещам или помочь проиллюстрировать, как всё работает (обеспечивая при этом компиляцию программ). Проницательные читатели заметят, что по вышеуказанным стандартам большинство этих комментариев ужасны. 🙂 Читая остальные руководства, имейте в виду, что комментарии служат намеренно образовательной цели, а не пытаются продемонстрировать, как выглядят хорошие комментарии.

Закомментирование кода

Преобразование одной или нескольких строк кода в комментарий называется закомментированием кода. Это предоставляет удобный способ (временно) исключить фрагменты вашего кода из включения в скомпилированную программу.

Чтобы закомментировать одну строку кода и временно превратить эту строку кода в комментарий, просто используйте однострочный комментарий // :

 std::cout 

// std::cout 

 std::cout 

// std::cout 

/* std::cout