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Для начинающихОбучениеПрограммирование

Назад

Оглавление

Вперед

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

| Python

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

В большинстве языков программирования присутствует синтаксис для блочных комментариев, которые охватывают несколько строк текста, например C или Java:

/*
Блочный комментарий. 
Охватывает несколько строк.
*/
int answer = 42;

Есть ли в Python аналогичные многострочные комментарии? Короткий ответ: нет, по крайней мере, не совсем точно так же.

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

Вариант 1: последовательные однострочные комментарии

Первым вариантом для комментирования нескольких строк кода в Python является простое использование # однострочного комментария для каждой строки:

# Это «блочный комментарий» в Python, сделанный
# из нескольких однострочных комментариев.
answer = 42

Большинство проектов Python следуют этому стилю, а руководство по стилю написания кода PEP 8 Python также рекомендует использовать повторяющиеся однострочные комментарии. Поэтому в большинстве случаях рекомендуется использовать их. Это также единственный способ написать «реальных» блочных комментариев в Python, которые игнорируется парсером.

Т.к. Python не поддерживает истинные многострочные комментарии, то для того чтобы закомментировать несколько строк кода требуется больше усилий. Приведём ряд полезных советов по ускорения работы с ними. У большинства редакторов кода есть шорткаты для блочных комментариев. Например, в Sublime Text достаточно просто выбирать пару строк, используя shift и клавиши курсора (или мышь), а затем нажимать cmd + /, чтобы закомментировать их все сразу.

Это даже работает в обратном порядке, то есть можно выбрать блок однострочных комментариев, и когда набирается клавиатурный шорткат cmd + /, весь блок снова раскомментируется.

Другие редакторы тоже поддерживают такую возможность: Atom, VS Code и даже Notepad++ имеют встроенные шорткаты для блочного комментирования в Python. Управление комментариями Python вручную – это неблагодарная работа, поэтому такая функция редактора может сэкономить много времени.

Вариант 2: использование многострочных строк вместо комментариев

Ещё одним вариантом для написания «правильных» многострочных комментариев в Python является использование многострочных строк с синтаксисом «»» (три кавычки). Например:

"""
Блок комментариев в Python, сделанный
из многострочной строковой константы.
"""
answer = 42

Можно использовать тройные кавычки для создания чего-то, что напоминает многострочный комментарий в Python. Необходимо убедиться, что правильно ввели «»», иначе будет получено исключение SyntaxError. Например, если нужно определить блочный комментарий внутри функции с помощью такого синтаксиса, то должны выполнить это следующим образом:

def add_stuff(a, b):
    result = a + b
    """
    Теперь возвращается результат.
    Ещё один пример многострочного комментария.
    """
    return result

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

Тем не менее, такая потерянная строковая константа не будет отображаться в байт-коде, фактически превращая её в многострочный комментарий. Далее доказательство того, что неиспользуемая строка не будет отображаться в дизассемблированном байт-коде CPython:

>>> import dis
>>> dis.dis(add_stuff)
  2    0 LOAD_FAST      0 (a)
       2 LOAD_FAST      1 (b)
       4 BINARY_ADD
       6 STORE_FAST     2 (result)
  8    8 LOAD_FAST      2 (result)
      10 RETURN_VALUE

Однако будьте осторожны, когда помещаете такие «комментарии» в код. Если строка следует сразу после сигнатуры функции, определения класса или в начале модуля, она превращается в docstring, которая имеет совсем другое значение в Python:

def add_stuff(a, b):
    """
    Это теперь связанная с docstring функция
     с объектом функции и доступным как
     метаданные времени выполнения.
    """
    result = a + b
    return result

Docstrings («строки документации») позволяют сопоставлять удобочитаемую документацию с модулями, функциями, классами и методами Python. Они отличаются от комментариев исходного кода.

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

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

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

Выводы

  • В отличие от других языков программирования Python не поддерживает многострочные комментарии из коробки.
  • Рекомендуемый способ закомментировать несколько строк кода в Python — использовать последовательные # однострочные комментарии. Это единственный способ получить «истинные» комментарии в исходном коде, которые удаляются парсером Python.
  • Вы можете использовать строки с тремя кавычками «»», чтобы создать что-то похожее на многострочные комментарии в Python, но это не идеальный метод, и такие могут превратиться в случайные docstrings.

C++ Комментарии

❮ Предыдущий Далее ❯

Комментарии C++

Комментарии можно использовать для объяснения кода C++ и для того, чтобы сделать его более читабельным. Его также можно использовать для предотвратить выполнение при тестировании альтернативного кода. Комментарии могут быть однострочными или многострочными.

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

Однострочные комментарии начинаются с двух косых черт ( // ).

Любой текст между // и концом строки игнорируется компилятором (не будет выполняться).

В этом примере используется однострочный комментарий перед строкой кода:

Пример

// Это комментарий
cout << "Hello World!";

Попробуйте сами »

В этом примере используется однострочный комментарий в конце строки кода:

Пример

cout << "Hello World!"; // Это комментарий

Попробуйте сами »

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

Многострочные комментарии начинаются с /* и заканчиваются на */ .

Любой текст между /* и */ будет игнорироваться компилятор:

Пример

/* Приведенный ниже код напечатает слова Hello World!
на экран, и это удивительно */
cout << "Hello World!";

Попробуйте сами »

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

Вам решать, что вы хотите использовать. Обычно мы используем // для коротких комментариев и /* */ для более длинных.

❮ Предыдущий Далее ❯


НОВИНКА

Мы только что запустили
Видео W3Schools

Узнать

ВЫБОР ЦВЕТА
КОД ИГРЫ

Играть в игру

Top Tutorials
Учебник по HTML
Учебник по CSS
Учебник по JavaScript
Учебник How To
Учебник по SQL
Учебник по Python
Учебник по W3.CSS
Учебник по Bootstrap
Учебник по PHP
Учебник по Java
Учебник по C++
Учебник по jQuery

Лучшие ссылки
Справочник по HTML
Справочник по CSS
Справочник по JavaScript
Справочник по SQL
Справочник по Python
Справочник по W3. CSS
Справочник по Bootstrap
Справочник по PHP
Цвета HTML
Справочник по Java
Справочник по Angular
Справочник по jQuery


0 Top1 Examples Примеры HTML
Примеры CSS
Примеры JavaScript
Примеры How To
Примеры SQL
Примеры Python
Примеры W3.CSS
Примеры Bootstrap
Примеры PHP
Примеры Java
Примеры XML
Примеры jQuery

FORUM | О

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

Авторское право 1999-2022 по данным Refsnes. Все права защищены.
W3Schools работает на основе W3.CSS.

Встроенный кодировщик Документация

Страница, которую вы искали, не существует. Используйте окно поиска или просмотрите темы ниже, чтобы найти нужную страницу.

Создание кода C и C++, оптимизированного для встраиваемых систем

  • Примечания к выпуску
  • Документация в формате PDF
  • Примечания к выпуску
  • Документация в формате PDF

Embedded Coder ® генерирует читаемый, компактный и быстрый код C и C++ для встроенных процессоров используется в массовом производстве. Он расширяет возможности MATLAB ® . Coder™ и Simulink ® Кодер с расширенными оптимизациями для точного управления сгенерированными функциями, файлы и данные. Эти оптимизации повышают эффективность кода и облегчают интеграцию с устаревший код, типы данных и параметры калибровки. Вы можете подключить стороннюю инструмент разработки для создания исполняемого файла для развертывания под ключ во встроенной системе или доска для быстрого прототипирования.

Embedded Coder предлагает встроенную поддержку стандартов программного обеспечения AUTOSAR, MISRA C ® и ASAP2. Он также предоставляет отчеты о прослеживаемости, код документации и автоматической проверки программного обеспечения для поддержки DO178, IEC 61508 и ISO 26262 разработка программного обеспечения. Код Embedded Coder является переносимым и может быть скомпилирован и выполнен на любом процессоре. В Кроме того, он предлагает пакеты поддержки с расширенными оптимизациями и драйверами устройств для конкретное оборудование.

Изучение основ Embedded Coder

Концепции генерации кода для развертывания во встроенных системах

Проектирование программных систем путем разработки алгоритмов компонентов, предназначенных для генерации кода и развертывания для встроенных систем

Настройка интерфейсов кода, создание и проверка результатов кода и создавать отчеты

Интеграция, защита, упаковка и перемещение сгенерированного кода; развертывание сгенерированного кода на поддерживаемом оборудовании

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

Настройка сгенерированного кода и инструментов генерации кода для проекта или организации

Настройка параметров, анализ производительности кода, тестирование

Генерация кода C/C++ из кода MATLAB для встраиваемых систем

Проверка отчетов об ошибках на наличие проблем и исправлений

Программное обеспечение по своей сути является сложным и не лишено ошибок. Вывод генератора кода может содержать ошибки, некоторые из которых не обнаруживаются компилятором. MathWorks сообщает об известных критических ошибках, доведенных до ее сведения, в своей системе отчетов об ошибках по адресу www.mathworks.com/support/bugreports/. В строке поиска введите фразу «Неверная генерация кода», чтобы получить отчет об известных ошибках, которые создают код, который может компилироваться и выполняться, но по-прежнему дает неверные ответы. Чтобы сохранить поиск, нажмите Сохранить поиск.

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

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

No related posts.