Как комментировать исходный программный код

Содержание:

Программисты не всегда правильно понимают, как комментировать код. А новички и вовсе не знают об этой функции. Многие пользователи сталкивались с комментированием, но могли не знать, что это такое. Рассмотрим основные моменты этого процесса.

Что такое комментирование

Это пояснение созданного программного кода, которое умещается в нескольких строках текста. Комментарии делают не для машины, а для программистов. Компиляторы и интерпретаторы не обращают внимания на комментарии. Они никак не влияют на работоспособность кода.

Ниже показан пример комментирования на языке C++. В этом случае комментарий начинается после 2 слешей (//):

Как комментировать исходный программный код

Как помогает комментирование

Разберемся, как комментирование помогает программисту в его работе:

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

Пример описания процесса в комментировании:

Как комментировать исходный программный код

Комментарии понадобятся не только в англоязычных языках программирования, но и в языках с русскими символами (например, 1С или ДРАКОН). Человеку может показаться, что в таких языках и так все понятно и не нужно ничего комментировать. Это ошибочное мнение. Код на русском языке так же забывается.

Оформление комментария в коде

Однострочный комментарий выделяется одиночным символом в начале и в конце строки. Многострочный имеет разные размеры, но поддерживается не всеми языками. Отмечается символами в начале и конце: /* и */.

Чтобы выделить комментарии, используют определенные символы. Они разнятся в зависимости от языка программирования:

  • // – однострочные в C, C++, PHP, C#, Java, JavaScript;
  • # – однострочные в PHP и Python;
  • /* */ – многострочные в C, C++, PHP, C#, Java, JavaScript.

Правила комментирования

Программисты во время комментирования придерживаются некоторых правил. Они упрощают работу и делают процесс понятнее.

Рассмотрим подробнее эти правила:

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

Как комментировать исходный программный код

  1. Комментируют все главные элементы кода. В них входят:
  • модули,
  • функции,
  • константы,
  • интерфейсы,
  • классы.
  1. Комментарии пишутся по делу и без воды. Только смысловая нагрузка и понятные слова. Не нужно писать сложные словосочетания, их просто никто не поймет.
  2. Запрещается писать оскорбительные комментарии. Также не рекомендуется употреблять жаргонные слова, которые понимаюттолько узкий круг людей.

Комментирование функций и библиотек

В комментариях к ним пишут:

  • данные о самом проекте;
  • назначение модуля;
  • имя разработчика;
  • версию программы;
  • лицензию на ПО.

В качестве примера рассмотрим комментарий в заголовке библиотеки Lodash:

Как комментировать исходный программный код

В заголовочном комментарии к функциям пишутся следующие данные:

  • описание действия функции;
  • условия работы функции;
  • входные параметры;
  • возвращаемое значение.

В качестве примера снова Lodash:

Как комментировать исходный программный код

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

Как комментировать исходный программный код

Автоматизация комментирования

Подобное предусмотрено с помощью IDE. Для этого используются теги-дескрипторы. Они начинаются с символа @.

Самые часто используемые теги-дескрипторы:

  • @author – идентификация автора исходного кода;
  • @param – определение параметра метода;
  • @see – ссылка;
  • @since – версия ПО;
  • @return – тип возвращаемых данных процедурой (функцией).

Подобные комментарии автоматически собирают программную документацию. Для сбора применяются генераторы документации. К примеру, для Java используют генератор javadoc.

Работает генератор документации достаточно просто. Он анализирует файл с исходным кодом и выискивает в нем имена:

  • классов,
  • свойств,
  • методов,
  • процедур,
  • функций.

Далее генератор связывает данные из комментариев с тегами. Затем создается документация, хранящаяся в разных текстовых форматах (HTML, PDF и других).

Во время создания фреймворков и библиотек формируются документы для API. Их нужно обновлять, т.к. они устаревают.

Комментирование сложного кода и рефакторинг

Большой и сложный код обязательно должен иметь поясняющие комментарии.

Код можно упростить: разбить его на функции, простые циклы и уменьшить все элементы. Через комментирование вы можете дать имена разбитым частям — они расскажут о значении каждого элемента.

К примеру, существует метод, сравнивающий числа a и b. Если a > b, метод возвращает true, а если a < b, то метод возвращает false:

Как комментировать исходный программный код

Этот код можно упростить, убрав из него блок if-else:

Как комментировать исходный программный код

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

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

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

Вопрос – Ответ

Комментирование доступно только на языках, которые указаны?

Нет, комментировать можно на всех языках. Принципы комментирования не сильно различаются.

Рефакторинг работает на всех языках программирования?

Да, это общий принцип упрощения программного кода. Он может использоваться не только в контексте комментирования.

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

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

Заключение

Подведем итоги. Мы рассмотрели в статье комментирование исходного кода и коснулись самых важных моментов:

  1. Что такое комментирование.
  2. Как оно помогает в программировании.
  3. Оформление комментария в коде.
  4. Правила комментирования.
  5. Комментирование функций и библиотек.
  6. Автоматизация комментирования.
  7. Комментирование сложного кода и рефакторинг.

Эти моменты помогут программисту проще работать со своим кодом и не теряться в его назначении.

Статья рассчитана не только на профессионалов, но и на новичков, которые еще не умеют программировать.

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

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

  • Верстать сайты;
  • Разрабатывать игры;
  • Запускать приложения;
  • Создавать бытовые программы для разной техники.

Курс идет 2 месяца. За это время вы научитесь всем азам и тонкостям frontend-разработки. Занятия ведут преподаватели — профессионалы в своей сфере. Они работают в крупных компаниях и с удовольствием поделятся нюансами своей работы. Вместе с основной академической базой вы получите практические рекомендации.

Занятия проходят 5 дней в неделю по 4 часа. После выпуска вы получите не только знания, но и портфолио своих работ. Вы сможете устроиться на работу в крупные компании и достойно зарабатывать. Средняя зарплата frontend-разработчика в России — 90 000 рублей.

Записывайтесь на курс сегодня и становитесь профессионалом уже завтра!

Присоединяйся к DevEducation — стань востребованным специалистом и построй карьеру в IT!