6. Комментарии в программах

6. Комментарии в программах

Содержание:
Что такое комментарии
Типы комментариев
Примеры
Использование комментариев
Комментарии как инструмент отладки

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

org 100h
start: mov ah, 9
mov dx, offset message
int 21h
mov ax,4C00h
int 21h
message db "Hello World!", 0Dh, 0Ah, '

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

Поэтому в программировании пошли сразу двумя путями:

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

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

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

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

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

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

Типы комментариев

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

0 REM Очистка экрана
10 CLS
15 REM Заголовок в первой строке
20 PRINT "Добро пожаловать!"
30 REM Цикл, выводящий линию под заголовком, на всю ширину экрана
40 FOR I=1 TO 80
50 PRINT "_"
60 NEXT I
70 END

Здесь в строках 0, 15 и 30 с помощью специальной команды REM (от английского «Remark» — комментарий, пометка) записаны комментарии, занимающие всю строку от начала (от команды REM) до конца строки. Эти строки при выполнении программы будут просто пропущены.

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

         .model tiny                  ; Модель памяти, используемая для .COM
         .code                        ; Начало сегмента кода
         org  100h                    ; Начальное значение счетчика - 100h
start:   mov  ah, 9                   ; Номер функции DOS - в AH
         mov  dx, offset message      ; Адрес строки - в DX
         int  21h                     ; Вызов системной функции DOS
         mov  ax, 4C00h
         int  21h                     ; Завершение программы
message  db   "Hello World!", 0Dh, 0Ah, '     ; Строка для вывода
         end  start                   ; Конец программы

Здесь признаком комментария является символ «;» и всё, что написано после него и до конца строки является текстом комментария и никакого отношения к программному коду (коду, который будет выполнен процессором) не имеет.

Нам осталось рассмотреть последний, пожалуй, наиболее функциональный тип комментариев. Эти комментарии подобны текстовым константам: у них есть начало и конец, при этом конец строки для них не имеет никакого значения. Такие комментарии есть практически во всех С-подобных языках. Для того чтобы начать такой комментарий в любом месте текста программы достаточно поставить пару символов «/*«, а для завершения — «*/«.

printf/*это сама команда*/("Сам текст...\n"); /* \n - команда перехода на новую строку */

Естественно, что всё, что находится между /* и */ а также сами эти символы будут пропущены при обработке, и компьютеру достанется только код самой команды:

printf("Сам текст...\n");

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

/* Команда вывода текста на экран консоли
   Эта команда может выводить не только текст
   Но вывод текста в ней наиболее простой */
printf("Сам текст...\n"); /* \n - команда перехода на новую строку */

Примеры

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

RUbasic

% Это пример строчного комментария

MS Small Basic

' Это пример строчного комментария

В языках C, C++, C#, Java, Java Script, PHP управляющие символы признака комментария идентичны:

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

Также PHP допускает в качестве символа строчного комментария кроме двух косых черт(«//») знак «#» — так же как и Python:

# Это однострочный комментарий в Python и PHP

кроме того, в Python многострочные комментарии могут быть созданы с использованием тройных кавычек («»» … «»»):

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

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

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

Заголовочные комментарии

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

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

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

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

/*
 * ani2.php -https://loli.github.io/ani2.php/
 * Version: 7.4
 * Licensed under the MIT license - http://opensource.org/licenses/MIT
 *
 * Copyright (c) 2023 Loli Soft
 */

Информативные комментарии

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

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

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

Описание блоков, классов и т.п.

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

/*
* Функция сложения двух чисел
* 
* @param {number float} num1 — первое число
* @param {number float} num2 — второе число
*
* @returns {number float} — возвращаемый результат сложения
*/
function add(num1, num2)  // передаваемые параметры — первое и второе число
{
    return num1 + num2; // возвращаемый результат сложения
}
//_________________________________________________

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

Задачи на будущее

Также комментарии можно с успехом использовать в качестве элементов списка задач, которые надо сделать. Это так называемые «TODO комментарии» («To do» — Надо сделать). В современных системах программирования текст в подобных комментариях предваряется словом «TODO»:

// TODO Реализовать более удобный интерфейс для данной функции!

Текущие рабочие комментарии

Комментарии могут просто содержать описание процесса разработки или заметки для себя. Что-то вроде:

// Здесь не все понятно - стоит проверить разные тестовые значения переменной f !!!!
или
// Это надо обязательно переделать !!!!!!
// Понять, как это может работать с длинными строками ?????

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

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

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

Комментарии как инструмент отладки

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

Да, прелесть комментариев не только в том, что они делают текст программ понятнее, с помощью комментариев можно изменять программный код в процессе работы над ним, не переписывая каждый раз все с начала. Вы можете хранить в тексте программы хоть десять вариантов кода одновременно, так, чтобы при этом использовался только один из них, а все остальные были «выключены» — для этого достаточно просто пометить как комментарии. Такой код в программировании называется закомментированным.

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

Главное: удалить признак комментария с фрагмента кода (раскомментировать его) — гораздо проще и быстрее, чем переписать код по-новой.

//printf("Ok!"); 
printf("Ошибка!");

Здесь отключена первая строка кода с помощью строчного комментария.

printf/*("Ok!")*/("Ошибка!");

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

В этих примерах будет выведено только слово «Ошибка!«.

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

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

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

//printf("***** Функция TextOn() - строка 345 *****");

Читаемость тестов программ

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

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

Некоторые адепты «изящного программировния» пишут в своих статьях о «ненужных», «тупых», «раздражающих», «избыточных» комментариях. Ну что ж, это всего лишь дело их личного вкуса, восприятия и… «крутизны» 🙂 . На самом же деле это чистой воды эмоции типа «нравится-не нравится». Ведь в конечном итоге оценивается результат — сама программа, а не комментарии.

Искусство (или просто навык) написания хороших комментариев является неотъемлемой частью искусства программирования.  Мы очень рекомендуем вам комментировать даже небольшие фрагменты вашего кода. Со временем вы поймете, какой стиль комментариев для вас более удобен и будете следовать ему почти автоматически. Написание качественных комментариев — это то, чему стоит учиться также как и самому программированию.

Итак:

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

На следующем занятии речь пойдет о различных операциях с данными.


Оглавление


Поделиться: 

Мы используем cookie-файлы для наилучшего представления нашего сайта. Продолжая использовать rubasic.ru, вы соглашаетесь на использование файлов cookie.
Понятно
Подробнее…