1.2 – Комментарии в C++

Добавлено 31 марта 2021 в 00:17

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

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

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

Однострочный комментарий C++ начинается с символов //, которые указывают компилятору игнорировать всё, от символов // до конца строки. Например:

std::cout << "Hello world!"; // Всё отсюда до конца строки игнорируется

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

std::cout << "Hello world!\n"; // std::cout живет в библиотеке iostream
std::cout << "It is very nice to meet you!\n"; // эти комментарии затрудняют чтение кода
std::cout << "Yeah!\n"; // особенно когда строки разной длины

Наличие комментариев справа от строки может затруднить чтение и кода, и комментария, особенно если строка длинная. Если строки достаточно короткие, комментарии можно просто выровнять (обычно по позиции табуляции), например:

std::cout << "Hello world!\n";                 // std::cout живет в библиотеке iostream
std::cout << "It is very nice to meet you!\n"; // это намного легче читать
std::cout << "Yeah!\n";                        // вам так не кажется?

Однако, если строки длинные, размещение комментариев справа может сделать ваши строки очень длинными. В этом случае однострочные комментарии часто помещаются над строкой, которую они комментируют:

// std::cout живет в библиотеке iostream
std::cout << "Hello world!\n";
 
// это намного легче читать
std::cout << "It is very nice to meet you!\n";
 
// вам так не кажется?
std::cout << "Yeah!\n";

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

Пары символов /* и */ отмечают многострочный комментарий в стиле 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 << 1;

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

//    std::cout << 1;

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

Незакомментированный код:

    std::cout << 1;
    std::cout << 2;
    std::cout << 3;

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

//    std::cout << 1;
//    std::cout << 2;
//    std::cout << 3;

или же

/*
    std::cout << 1;
    std::cout << 2;
    std::cout << 3;
*/

Есть несколько причин, по которым вы можете захотеть это сделать:

  1. Вы работаете над новым фрагментом кода, который еще не компилируется, и вам нужно запустить программу. Компилятор не позволит вам скомпилировать код, если есть ошибки компиляции. Комментирование кода, который не компилируется, позволит программе скомпилироватьсь, чтобы вы могли ее запустить. Когда вы будете готовы, вы сможете раскомментировать код и продолжить работу над ним.
  2. Вы написали новый код, который компилируется, но работает некорректно, и у вас нет времени исправить его. Комментирование неработающего кода гарантирует, что он не будет выполняться и не вызовет проблемы, пока вы не исправите его.
  3. Поиск источника ошибки. Если программа не дает желаемых результатов (или дает сбой), иногда может быть полезно отключить части вашего кода, чтобы посмотреть, можете ли вы определить причину, по которой она работает некорректно. Если вы закомментировали одну или несколько строк кода, и ваша программа начинает работать должным образом (или перестает давать сбой), скорее всего, то, что вы в последний раз закомментировали, было частью проблемы. Затем вы можете выяснить, почему эти строки кода вызывают проблему.
  4. Вы хотите заменить один фрагмент кода другим фрагментом кода. Вместо того чтобы просто удалять исходный код, вы можете закомментировать его и оставить для справки, пока не убедитесь, что новый код работает правильно. Убедившись, что ваш новый код работает, вы можете удалить старый закомментированный код. Если вам не удается заставить новый код работать, вы всегда можете удалить новый код и раскомментировать старый код, чтобы вернуться к тому, что было раньше.

Закомментирование кода – обычное дело при разработке, поэтому многие IDE поддерживают комментирование выделенного участка кода. Доступ к этой функции зависит от IDE.

Резюме

  • На уровне библиотеки, программы или функции используйте комментарии, чтобы описать что делается.
  • Внутри библиотеки, программы или функции используйте комментарии, чтобы описать, как это сделать.
  • На уровне инструкции используйте комментарии, чтобы объяснить, почему.

Оригинал статьи:

  • 1.2 — Comments

Теги

C++ / CppLearnCppДля начинающихОбучениеПрограммирование

Назад

Оглавление

Вперед

Комментарии в программировании | это… Что такое Комментарии в программировании?

Коммента́рии — пояснения к исходному тексту программы, находящиеся непосредственно внутри комментируемого кода. Синтаксис комментариев определяется языком программирования. С точки зрения компилятора или интерпретатора, комментарии — часть текста программы, не влияющая на её семантику. Комментарии не оказывают никакого влияния на результат компиляции программы или её интерпретацию. Помимо исходных текстов программ, комментарии также применяются в языках разметки и языках описания.

Содержание

  • 1 Назначение комментариев
  • 2 Однострочные и многострочные комментарии
  • 3 Аннотации
  • 4 Автоматическая генерация документации
  • 5 Трансляция программ
  • 6 В различных языках и средах программирования
  • 7 Специальные комментарии
  • 8 См. также

Назначение комментариев

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

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

Комментарии часто используются для временного отключения части кода. В языках C и C++, некоторые рекомендуют использовать с той же целью директивы препроцессора (#if 0 … #endif).

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

С точки зрения синтаксиса, существуют два вида комментариев. Многострочный комментарий может иметь любую длину, он отмечается специальными символами в начале и конце (например, /* */). Некоторые языки позволяют вложение многострочных комментариев, другие — нет. Однострочный комментарий отмечается специальным символом в начале (например, //) и продолжается до конца строки. Обычно допускается вложение однострочных комментариев в другие, как одно- так и многострочные комментарии. Способы записи можно чередовать, с точки зрения семантики они одинаковы.

Аннотации

Другой вид комментариев — аннотации — применяется в набросках доказательств правильности программ. Такие комментарии описывают состояние компьютера, когда программа в процессе выполнения достигнет точки, где расположен комментарий. Программа, снабжённая комментариями-аннотациями, называется аннотированной программой.

Автоматическая генерация документации

Специальным образом оформленные комментарии (т. н. документирующие комментарии) используются для автоматического создания документации, в первую очередь, к библиотекам функций или классов. Для этого используются генераторы документации, например, такие как [1] для языка doxygen [2] для C и C++ и др. В некоторых средах программирования (например, Python) документирующие комментарии используются в качестве интерактивной подсказки по интерфейсу классов и функций.

Трансляция программ

Во время трансляции комментарии распознаются на стадии лексического анализа (и, соответственно, считаются лексемами). Распознавание на стадии препроцессирования накладно и даже чревато ошибками; включение комментариев в синтаксические диаграммы практически невозможно.

В различных языках и средах программирования

  • Ассемблер
; однострочный комментарий
COMMENT +
… Многострочный комментарий.
+ Строка с этим символом завершает комментарий, вместо плюса может быть другой символ.
  • Форт
\ стандартный однострочный комментарий
( Комментарий до закрывающей скобки. Может быть многострочным (зависит от реализации). Пробел после открывающей скобки обязателен.)
  • REM однострочный комментарий

Многострочные комментарии Visual Studio 2019 C++

Задавать вопрос

спросил

Изменено 3 года, 6 месяцев назад

Просмотрено 3к раз

Когда линия выделена частично, это приводит к /**/ Комментарий в стиле C:

 #include /**/
#include 
#include <узел.h>

Когда одна или несколько строк выделены частично, это приводит к // комментарию в стиле C++:

 //#include 
//# включаем 
#include <узел.h>

Все параметры комментариев VS2019 имеют следующее поведение: Переключить комментарий строки ( Ctrl+K, Ctrl+/ ), Переключить комментарий блока ( Ctrl+Shift+/ ), Выбор комментария ( Ctrl+K, Ctrl+C ).

По-разному ли ведут себя эти параметры на других языках?

Я знаю о недостатках комментариев в стиле C++, но хотел бы иметь возможность использовать их для многострочных комментариев там, где это необходимо:

 /*
#include 
#include 
*/
#include <узел.h>

Можно ли настроить Visual Studio 2019 таким образом?

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

  • c++
  • визуальная студия
  • комментарии
  • визуальная студия-2019
3

Насколько я понимаю, вы должны выбрать всю строку (т.е. с самого первого символа строки), чтобы использовать комментарии С++ для нескольких строк.

Если среди выбранных строк есть комментарии, Ctrl+K,Ctrl+C создаст комментарии в стиле C++, даже если выделение начинается не с начала строк.

Например: Выберите содержимое, как показано:

А затем Ctrl+K, Ctrl+C

Если выделить всю строку, включая пробелы:

90 002 А затем Ctrl+K, Ctrl+C , вы получите комментарий в стиле C++ для многострочных комментариев

2

Зарегистрируйтесь или войдите в систему

Зарегистрируйтесь с помощью Google

Зарегистрироваться через Facebook

Зарегистрируйтесь, используя адрес электронной почты и пароль

Опубликовать как гость

Электронная почта

Обязательно, но не отображается

Опубликовать как гость

Электронная почта

Требуется, но не отображается

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

Комментарии в C — Программирование микроконтроллеров на языке C

  • Автор сообщения: