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

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

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, 15 и 30 с помощью специальной команды REM (от английского «Remark» — комментарий, пометка) записаны комментарии, занимающие всю строку от начала (от команды REM) до конца строки. Эти строки при выполнении программы будут просто пропущены.

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

Комментарии Python (Comments in Python)

.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 */

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Итак:

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

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

Источник: rubasic.ru

Комментарии в коде (Visual Basic)

В примерах кодов часто встречается символ начала комментария ( ‘ ). Этот символ указывает компилятору Visual Basic игнорировать следующий текст или комментарий. Комментарии — это краткие заметки, внесенные в код, чтобы сделать чтение кода более легким.

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

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

‘ This is a comment beginning at the left edge of the screen. text1.Text = «Hi!» ‘ This is an inline comment.

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

‘ This comment is too long to fit on a single line, so we break ‘ it into two lines. Some comments might need three or more lines.

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

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

Это предложения; Visual Basic не применяет правила для добавления комментариев. В комментарий по желанию автора кода может быть включена любая информация.

Тип комментария Описание комментария

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

Также рекомендуется принять во внимание следующие моменты.

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

Вы можете добавить или удалить символы комментариев для блока кода, выбрав одну или несколько строк кода и выбрав кнопки Комментарий () и Раскомментировать () на панели инструментов Изменить .

Кроме того, можно добавить в код комментарии, поставив в начале текста ключевое слово REM . ‘ Однако символ и кнопкиРаскомментировать / комментарии проще в использовании и требуют меньше места и памяти.

См. также раздел

• Основные инстинкты— документирование кода с помощью xml-комментариев
• Практическое руководство. Создание XML-документации
• XML-теги для комментариев
• Соглашения о структуре программы и коде
• Оператор REM

Источник: learn.microsoft.com

Комментарии в Python 3

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

• сделать код более читабельным;
• объяснить, что и зачем делает код;
• предотвратить выполнение части кода при его тестировании/выполнении;
• оставить заметку о том, что необходимо сделать/переделать/убрать.

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

В этой статье вы узнаете, как оставлять комментарии в Python 3 , что такое Docstring и PEP.

Комментарии в Python

В разных языках программирования у комментариев разный синтаксис. Часто это двойной слеш (//). В Python 3 комментарии в коде начинаются со знака «#». Например:

#Код выводит в консоль строку «Hello, World!» print(«Hello, World!»)

Также комментарий можно разместить прямо в строке с кодом:

print(«Hello, World!») #Код выводит в консоль строку «Hello, World!»

Комментарии должны быть полезны для читателя. Например, такой комментарий не принесет пользы:

#что-то этот код явно делает
print(«Hello, World!»)

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

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

Предположим, нам нужно закомментировать такой код:

db_lp = sqlite3.connect(‘login_password.db’)
cursor_db = db_lp.cursor()
sql_create = »’CREATE TABLE passwords(
login TEXT PRIMARY KEY,
password TEXT NOT NULL);»’

cursor_db.execute(sql_create)
db_lp.commit()

cursor_db.close()
db_lp.close()

Это, кстати, код из нашего туториала по созданию веб-приложения с помощью Flask. Прочитать его можно здесь . Цель комментирования — сделать этот блок кода понятным. Его можно закомментировать таким образом:

db_lp = sqlite3.connect(‘login_password.db’) #Создаем базу данных login_password
cursor_db = db_lp.cursor() #Объект класса Cursor для выполнения SQL-запросов

#SQL-запрос для создания таблицы password в базе данных
sql_create = »’CREATE TABLE passwords(
login TEXT PRIMARY KEY,
password TEXT NOT NULL);»’

cursor_db.execute(sql_create) #Выполняем запрос sql_create
db_lp.commit() #Подтверждаем изменения

#Закрываем Cursor и базу данных
cursor_db.close()
db_lp.close()

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

• PyCharm: Ctrl + /;
• Visual Studio Code: чтобы закомментировать/раскомментировать строку Ctrl + /, чтобы блок кода – Shift + Alt + A;
• Eclipse: чтобы закомментировать/раскомментировать строку Ctrl + /, чтобы блок кода – Ctrl + Shift + /;
• Visual Studio: Ctrl + K затем Ctrl + C, чтобы закомментировать блок кода, и Ctrl + K затем Ctrl + U, чтобы раскомментировать блок кода.

Docstring в Python

Docstring — это строковый литерал, который размещается сразу после объявления модуля, функции, класса и других структур. Это удобный способ документирования кода, к которому можно обращаться. Docstring появился в Python в 2001 году и описан в PEP 257 .

Что такое PEP?

Развитие языка Python происходит по четко регламентированному процессу создания, обсуждения, отбора и реализации документов PEP (Python Enhancement Proposal). В PEP размещаются предложения по развитию языка: внедрению новых функций, изменению существующих и т.п. Одним из самых известных (и полезных) документов PEP является PEP 8 — в нем отображен свод рекомендаций и соглашений по написанию кода на Python.

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

Вернемся в Docstring. Docstring — первая инструкция в объявлении объекта. Вот пример:

def function (x,y,z):
«»» Docstring этой функции»»»
def inner_function ():
«»» Docstring вложенной функции «»»

Синтаксис Docstring — это три кавычки в начале и в конце. Также можно использовать вместо кавычек апострофы и не три, а два или один символ. Но PEP 257 рекомендует использовать именно три кавычки.

К docstring объекта можно обратиться с помощью метода __doc__:

def subtraction (a,b):
«»»Функция вычитает из числа a число b»»»
return (a-b)
print(subtraction.__doc__)

Результат: ф ункция вычитает из числа a число b.

Также свойство __doc__ можно использовать для получения информации о встроенных методах Python, например print:

print(print.__doc__)
print(value, . sep=’ ‘, end=’n’, file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.

Строковые литералы, встречающиеся где-то в коде Python, также могут выполнять роль документации. Они не будут распознаны компилятором байт-кода Python и не будут доступны во время выполнения программы с помощью свойства __doc__ . Но есть два дополнительных типа docstring, которые могут быть извлечены из кода программными инструментами.

Additional docstring

Additional docstring — это строковые литералы, которые игнорируются компилятором Python, но при этом распознаются средствами Docutils. Они размещаются сразу после docstring. Вот пример:

def function(arg):
«»»Это docstring этой функции. Он будет доступен с помощью свойства __doc__.»»»
«»»
Это additional docstring, он будет проигнорирован компилятором, но распознан Docutils.
«»»
pass

Attribute docstrings

Attribute docstring — это строковые литералы, которые встречаются сразу после простого присваивания на уровне модуля, класса или метода __init__. Например:

def f(x):
«»»Это docstring этой функции. Он будет доступен с помощью свойства __doc__»»»
return x**2
f.a = 1
«»» Это attribute docstring для атрибута функции f.a, он будет проигнорирован компилятором, но распознан Docutils.»»»

Вот основные рекомендации из PEP 257 по использованию docstring:

• После всех docstring оставляйте пустую строку.
• Docstring скрипта должен представлять собой сообщение «о правильном использовании», который, возможно, будет выведен пользователю при вызове скрипта с неправильными аргументами. Docstring должен описывать функционал, синтаксис параметров, переменные среды и используемые файлы.
• Docstring модуля должен содержать список важных объектов и однострочное пояснение для каждого из них.
• Docstring функции или метода должен описывать поведение, аргументы, return, возможные исключения и ограничения работы.
• Docstring класса должен содержать методы, переменные экземпляра и описывать поведение класса.
• Конструктор класса должен иметь свою отдельную документационную строку для метода __init__.
• Если класс является потомком и его поведение в основном наследуется от основного класса, в его документации необходимо упомянуть об этом и описать возможные различия.

Полезные инструменты

Вместо заключения приведем список инструментов, которые будут полезны при работе с PEP 8 и комментариями в Python 3:

• pycodestyle — проверяет соответствие вашего кода PEP 8;
• Black — форматирует код в соответствии со стандартом PEP 8 (в основном);
• Doxygen, PyDoc, pdoc — автоматически формируют документацию из docstring.

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

Источник: timeweb.cloud