C многострочный комментарий: C++ — Комментарии в коде

Зачем нужны комментарии в коде и как их правильно составлять

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

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

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

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

def calculate_si_amount(principal, rate, time):
  interest = (principal*rate*time)/100



  return principal+interest

После отладки их лучше удалить, оставив строки:

def calculate_si_amount(principal, rate, time):
  interest = (principal*rate*time)/100
  return principal+interest

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

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

Пример на языке JavaScript:

Здесь и сам метод Number.isFinite (), и глобальная функция isFinite () проверяют, является ли параметр value конечным числом (то есть не ± ∞). Но если value = null, то isFinite (value) возвращает true, а Number.isFinite (value) возвращает false. Поэтому Number.isFinite (value) нельзя менять на isFinite (value).

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

cost = quantity * 2 * price;

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

Правильно будет так:

cost = quantity * 2 * price;

В любом случае, старайтесь писать поясняющие комментарии как можно реже.

Как правильно комментировать код / Хабр

Как-то раз сидел в аудитории с ноутом около розетки, а в это время на соседней парте принимался зачет по программированию. Я не сильно вникал в суть вопросов на которые общались студент и преподаватель, назовем его Иван Ивановичем. Разговор был довольно спокойный и тихий, но у меня получилось выхватить часть. Преподаватель говорил о комментариях (видимо сдавалась программа, в которой не было ни строчки комментариев). Меня этот момент заинтересовал и я начал прислушиваться. Было замечено, что мне тоже интересно, преподаватель начал импровизированную лекцию. Ниже представлен тот небольшой кусок знаний который я тогда вынес с этой 5ти минутной лекции.

Хочется сразу предупредить, что для многих описанное здесь — очевидные вещи, однако, новичкам в коллективном программировании (когда над кодом работают 2 и более программиста) и студентам будет полезно. Кроме того, все изложенные ниже советы имеют альтернативу и могут быть использованы лишь частично.

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

Как писать код сразу с комментариями

По сути говоря, на той лекции принцип TDD (Test-driven development, разработка через тестирование) был перенесен на уровень ниже. Не помню как это звучало в оригинале, но по сути «Опиши комментариями структуру кода». На примере (сильно утрированном, почему — ниже) кода программы, складывающей два числа, этот принцип будет выглядеть так:

int main()
{
     // Принять от пользователя два числа
     // Завести переменную для результата сложения
     // Вернуть результат сложения

     return 0;
}

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

...
int main()
{
     double a,b;
     // Принять от пользователя два числа
     cin>>a;
     cin>>b;
     //Завести переменную для результата сложения
     double sum = a+b;
     // Вернуть результат сложения
     cout<<sum;

     return 0;
}

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

Теперь представим «чисто гипотетическую» ситуацию, когда уже имеется код в 200 000 строк, написанный гениальным программистом криворуким индусом и не содержит ни строчки комментария. Однако вам необходимо, мало того что убить этого программиста понять этот код, но и сопровождать его в дальнейшем. Вы даже разобрались в этом коде, и будучи приличным человеком, решили дополнить код комментариями для, так сказать, будущих поколений. Но возникает вопрос: как?

Как комментировать уже существующий код

Ответ на этот вопрос довольно прост: комментируем сущности от родителя к потомку: класс -> метод -> код внутри метода (если необходимо).

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

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

Относительно второго пункта стоит немного пояснить и привести пример: вставка 100 строк ассемблера код на C! Вы на нее смотрите и пишите комментарий // Многа букаф! Ниасилил
После этого человек пришедший после вашего увольнения на ваше место видит этот комментарий и… все! Он даже не будет пытаться в нем разобраться и эта ваша запись будет клеймом на этом куске кода до тех пор пока его не уберут (либо код, либо комментарий).

Напоследок

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

Комментарии в коде — полезные, бессмысленные, вредные? / Хабр

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

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

Итак:

1. Комментарий может быть полезным, бессмысленным или вредным.

2. Если комментарий не несет явно видимой пользы, то он скорее всего вреден.

3. Комментарии бесполезны / вредны чаще, чем кажется. Отсутствие комментария лучше, чем бесполезный комментарий.

4. Перед тем, как написать комментарий — подумайте дважды, а может не стоит? 🙂
(5. После того, как вы решили, что комментарий все-таки не нужен, посмотрите трижды — а код точно кристалльно понятен?:))

Про полезные комментарии все ясно. Когда:

— достаточно прочитать 6 строк комментария вместо 80 строк кода метода с бизнес-логикой

— в комментарии дается ссылка на реализуемый малоизвестный алгоритм или структуру данных (например — «для поиска подстроки используется алгоритм Ахо — Корасик», ссылка на википедию или спец. сайт)

— комментарий поясняет, почему автор использует не тот подход, который читающий код скорее всего ожидает тут увидеть (например, написанный руками SQL запрос вместо работы через ORM фреймворк, или почему для поиска в XML используется regexp, а не XPath)

— в комментарии дан короткий ясный пример использования (особенно, если это какой-нибудь custom Ant task или что-то подобное),

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

А теперь посмотрим на некоторый другой часто встречающийся пример.

Такой комментарий обычно создается IDE по умолчанию при генерации геттеров-сеттеров для поля объекта (в свой очередь, если бы в Java были свойства, и необходимые синтетические методы генерились компилятором прозрачно для программиста, этой проблемы бы тоже не было :)).

1. /**
2. * return the enterpriseName
3. */
4. public String getEnterpriseName() {
5. return enterpriseName;
6. }

Комментарий, очевидно, не нужен. Ничего нетривиального в коде нет, комментарий по сути дублирует код. Кроме того — комментарий здесь занимает три строки в редакторе кода. Т.е. ровно столько же, сколько и сам код. Мало того что сам код, по сути, синтетический, + из-за Java Code Conventions растягивается три строчки ради удобочитаемости, так еще и комментарий отъедает место.

Java и так маловыразительный язык (с точки зрения среднего количества полезных действия на строку кода) по сравнению с, например, Ruby или Groovy, так зачем тратить экранное место под лишние комментарии.

Тут, конечно, есть тонкий момент. Если код с подобными комментариями — это часть public API какой нибудь generic библиотеки, и никто из пользующихся ей программистов почти никогда не смотрит ее исходники, а смотрит Javadoc — тогда это еще нормально. Но если этот код находится в каком нибудь модуле, разработываемом нами, и исходники этого класса смотрят чаще, чем документацию к нему (что почти всегда верно) — тогда это ИМХО, тот случай, когда правило «любой элемент API должен иметь комментарий» должно применяться с большой осторожностью.

Рассмотренный пример часто дополнительно ухудшается тем, что в комментарий запихиваются теги param, return, которые часто полезной информации не несут, а вот место съедают. Например:

/**

*

* Some description.

* param paramName1 paramName1

* param paramName2 paramName2

* param paramName3 paramName3

* return the name of user

*/

public String getUserName(String paramName1, int paramName2, int paramName2) {

/* какой то простой прямолинейный код*/

}

(Забавно, что часто в коде есть такие бессмысленные комментарии, а в реально сложных частях комментариев мало :))

И напоследок еще пример.

// Временный хак, т.к. возможность сделать нормально сейчас не поддерживается,

// а сделать надо срочно. По совету [senior developer name], хакнул так.

// 21/04/2004, [developer name].

В некоторых примерах я частично утрирую, но общая идея от этого не меняется.

Updated:

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

Стив МакКоннелл. Совершенный код. www.ozon.ru/context/detail/id/5508646

Мартин Фаулер. Рефакторинг. Улучшение существующего кода. www.ozon.ru/context/detail/id/4952415

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

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

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

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

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

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

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

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

Аннотации

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

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

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

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

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

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

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

COMMENT +

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

+ Строка с этим символом завершает комментарий, вместо плюса может быть другой символ.

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

( Комментарий до закрывающей скобки. Может быть многострочным (зависит от реализации). Пробел после открывающей скобки обязателен.)

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

Использование комментариев в CSS — это отличный способ пояснить написанные стили и структурировать разделы кода. Умело добавленные комментарии могут сделать код более понятным. Это особенно важно для проектов, над которыми работают целые команды. Следует знать, что комментарии не отображаются на странице в браузере. Они носят информационный характер и не влияют на визуальное отображение сайта.

Как добавить CSS комментарий

Добавить CSS комментарий легко: просто заключите свой комментарий между открывающимся и закрывающимся тегом:

•	Начните свой комментарий, добавив /*
•	Закройте комментарий, добавив  */

Он может быть однострочным или многострочным.

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

div#border_red {    
  border: thin solid red;      
} /* красная граница пример */
И многострочный пример:
/*************************** 
**************************** 
Многострочный комментарий
**************************** 
***************************/

Разделение на секции

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

/*----------------------- Заголовок начинается здесь ------------------------------ */

«Комментирование» кода

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

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

Советы по CSS комментированию

1. Комментарии могут занимать несколько строк;
2. Комментарии могут включать в себя CSS элементы, которые не нужно отображать в браузере и удалять полностью. Это хороший способ отладки стилей сайта;
3. Используйте комментарии, когда пишете сложный CSS, чтобы добавить разъяснения и сообщить разработчикам о нюансах, которые стоит знать;
4. Комментарии в HTML CSS могут также включать в себя такую метаинформацию, как:

• Автор;
• дата создания;
• информация об авторских правах.

Эффективность

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

Данная публикация представляет собой перевод статьи «How to Insert a CSS Comment» , подготовленной дружной командой проекта Интернет-технологии.ру

телеграм канал. Подпишись, будет полезно!

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

У этого термина существуют и другие значения, см. Комментарий.

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

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

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

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

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

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

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

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

Аннотации

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

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

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

Документирующие комментарии как правило оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.

Пример документирующего комментария

/**
* Имя или краткое описание объекта
* 
* Развернутое описание
* 
* @имя_дескриптора значение
* @return тип_данных
*/

В некоторых средах программирования (например, Eclipse, NetBeans, Python, Visual Studio) документирующие комментарии используются в качестве интерактивной подсказки по интерфейсу классов и функций.

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

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

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

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

COMMENT +

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

+ Строка с этим символом завершает комментарий, вместо плюса может быть другой символ.

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

( Комментарий до закрывающей скобки. Может быть многострочным (зависит от реализации). Пробел после открывающей скобки обязателен.)

' однострочный комментарий> — поддерживается не во всех диалектах

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

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

• BAT-файлы и команды DOS

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

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

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

/* многострочный комментарий */

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

# однострочный комментарий (для PHP)

Способ комментирования больших кусков кода в C/C++. Используется не для написания комментариев к программе, а для временного сокрытия части функциональности (в Java и JavaScript невозможен):

#if 0

…кусок кода…

#endif

* (на седьмой позиции) — однострочный комментарий

(* многострочный комментарий *)

{ многострочный комментарий }

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

c однострочный комментарий (в старых версиях Фортрана после латинской c должно идти 5 пробелов)

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

<!-- многострочный комментарий -->

• Конфигурационные (ini) файлы

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

• Файлы реестра Windows (REG)

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

• Система аналитических вычислений Mathematica

(* многострочный комментарий *)

• Система аналитических вычислений Maple

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

(* многострочный комментарий *)

{ многострочный комментарий }

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

=pod
аналог многострочного комментария, используется для написания документации

=cut

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

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

/* многострочный комментарий */

=begin

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

=end

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

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

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

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

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

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

--[[многострочный

комментарий]]

--[[многострочный

комментарий]]--

Специальные комментарии

Комментарии должны игнорироваться транслятором, но на практике это не всегда так. Некоторые специальные команды транслятору, сильно зависящие от реализации языка программирования, часто оформляются как комментарии.

Например в диалекте Турбо Паскаль псевдокомментарии {$I-} и {$I+} используются для отключения и включения стандартного контроля ошибок ввода-вывода. Похожие специальные комментарии используются в языке разметки HTML для указания типа SGML-документа, «экранирования» таблиц стилей и сценариев на языках JavaScript и VBScript:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
…
<STYLE TYPE="text/css">
<!--
… описание стилей
-->
</STYLE>
…
<SCRIPT TYPE="text/javascript">
 <!-- скрыть содержимое сценария от старых браузеров
 … код сценария на JavaScript
 // конец скрытого содержимого -->
</SCRIPT>

Некоторые комментарии программисты используют в ходе своей работы. Подобные комментарии особенно полезны, когда над одним кодом работает несколько разработчиков. Так, комментарием TODO обычно помечают участок кода, который программист оставляет незавершённым, чтобы вернуться к нему позже. Комментарий FIXME помечает обнаруженную ошибку, которую решают исправить позже. Комментарий XXX обозначает найденную критическую ошибку, без исправления которой нельзя продолжать дальнейшую работу.

Примечания

См. также

Многострочный комментарий в программировании на C

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

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

1. Многострочный комментарий можно разместить где угодно.
2. Многострочный комментарий начинается с / * .
3. Многострочный комментарий заканчивается на * / .
4. Любые символы, написанные между '/ *' и '* /' , игнорируются компилятором.
5. Его можно разделить на несколько строк

Программа C: Многострочный комментарий C

 #include 
пустая функция()
{
printf ("Привет");
/ * Мульти
Линия
Комментарий
* /
printf ("По");
} 

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

 #include 
пустая функция()
{
printf ("Привет");
/ * --------------------------------------------
------------------ Игнорируется компилятором -------
--------------------------------------------
* /
printf ("По");
} 

В следующих уроках мы изучим различные правила написания комментариев.

Различные способы использования многострочного комментария:

Способ 1: Используется для названия программы и документации

 / ***************************************
* Название: Название программы *
* Автор: Имя автора *
*************************************** / 

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

необходимо написать документацию по программе.

Статья по теме: Как написать читаемый и кэширующий исходный код?

Способ 2: Используется для более подробного комментария в программе

 / * следующая строка используется для получения -
1.Количество Заказчика
2. он вернет целое число
* /

int var = getCount (стр); 

ИЛИ

 int var = getCount (строка); / * Используется для подсчета
Количество человек
Настоящее время */

pritnf ("count:% d", var); 

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

.

файл — подсчитать все строки между многострочным комментарием с помощью c ++

Переполнение стека

1. Около

2. Продукты

3. Для команд

1. Переполнение стека
   Общественные вопросы и ответы

2. Переполнение стека для команд
   Где разработчики и технологи делятся частными знаниями с коллегами

3. Вакансии
   Программирование и связанные с ним технические возможности карьерного роста

4. Талант
   Нанимайте технических специалистов и создавайте свой бренд работодателя

5. Реклама
   Обратитесь к разработчикам и технологам со всего мира

6. О компании

Загрузка…

.

ply — регулярное выражение Python для поиска многострочного комментария C, охватывающего несколько строк

Переполнение стека

1. Около

2. Продукты

3. Для команд

1. Переполнение стека
   Общественные вопросы и ответы

2. Переполнение стека для команд
   Где разработчики и технологи делятся частными знаниями с коллегами

3. Вакансии
   Программирование и связанные с ним технические возможности карьерного роста

4. Талант
   Нанимайте технических специалистов и создавайте свой бренд работодателя

5. Реклама
   Обратитесь к разработчикам и технологам со всего мира

6. О компании

Загрузка…

.

1.2 — Комментарии | Learn C ++

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Причина: мы уже видим, что прицел устанавливается на 0, посмотрев на оператор

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

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

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

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

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

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

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

Хороших отзывов:

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

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

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

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

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

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

Без комментариев:

Прокомментировано:

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

Без комментариев:

Прокомментировано:

или

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

1) Вы работаете над новым фрагментом кода, который еще не компилируется, и вам нужно запустить программу.Компилятор не позволит вам скомпилировать код, если есть ошибки компилятора. Комментирование кода, который не компилируется, позволит программе скомпилировать, чтобы вы могли ее запустить. Когда вы будете готовы, вы можете раскомментировать код и продолжить работу над ним.

2) Вы написали новый код, который компилируется, но работает некорректно, и у вас нет времени исправить это позже. Если вы закомментируете неисправный код, он не будет выполняться и вызовет проблемы, пока вы не исправите его.

3) Найти источник ошибки.Если программа не дает желаемых результатов (или дает сбой), иногда может быть полезно отключить части вашего кода, чтобы посмотреть, сможете ли вы определить причину, по которой она работает некорректно. Если вы закомментировали одну или несколько строк кода, и ваша программа начинает работать должным образом (или перестает давать сбой), скорее всего, то, что вы в последний раз закомментировали, было частью проблемы. Затем вы можете выяснить, почему эти строки кода вызывают проблему.

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

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

Вы можете прокомментировать или раскомментировать выделенный фрагмент с помощью меню «Правка»> «Дополнительно»> «Комментарий» (или «Раскомментировать выделенный фрагмент»).

Вы можете прокомментировать или раскомментировать выделенный фрагмент с помощью меню «Правка»> «Комментарий» (или «Раскомментировать», «Переключить комментарий» или любой другой инструмент для комментирования).

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

Если вам действительно нужно закомментировать блок кода, содержащий многострочные комментарии, вы также можете рассмотреть возможность использования директивы препроцессора #if 0 , которую мы обсуждаем в уроке 2.10 — Введение в препроцессор.

Сводка

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

.