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

HTML-комментарии

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

Комментарий в HTML-коде задаётся так:

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

• Для комментирования кода. Всегда полезно оставить подсказку.
• Для временного отключения кода. Удалять код неудобно, так как его надо будет восстанавливать, а закомментировать и потом раскомментировать — самое лучшее решение.

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

Чтобы быстро закомментировать или раскомментировать строку кода в HTML или CSS редакторе, можете использовать сочетание клавиш ctrl + / или cmd + / .

Перейти к заданию

• index.html Сплит-режим
• style.css Сплит-режим

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Напоследок

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

Зачем комментировать исходный код и как это делать правильно

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

Марина Демидова

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

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

Знакомый, наверно, каждому пример со словами на русском или английском языке после двух слешей — так обычно выглядят комментарии:

// Программа,которую нужно выполнить,чтобы стать программистом print('Hello, World!')

Чем комментарии могут помочь программисту

Комментарии, в зависимости от ситуации, делают сразу несколько полезных вещей:

• Помогают быстрее разобраться в коде — если появилась ошибка или нужно что-то изменить d программе. Это важно и разработчику, и тем, кто будет заниматься кодом после него.
• Не дают запутаться в логике — при создании новых библиотек, процедур, функций и системных переменных.
• Объясняют результаты работы — при отладке или проверке программы. Это понимание необходимо тестировщикам из отдела QA .
• Описывают сложные алгоритмы и формулы — в математических, физических или экономических расчётах и других сложных вычислениях. Это позволяет разобраться в готовом коде тем, у кого нет глубоких знаний в какой-то предметной области.

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

Комментарии нужны даже в языках с русскоязычным синтаксисом, вроде 1C или ДРАКОН . Может показаться, что там все и без комментариев понятно, но это опасное заблуждение: русскоязычный код забывается так же легко, как и англоязычный.

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

Комментарии бывают совсем короткими, длиной не более строки, и большими, многострочными.

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

Для выделения комментариев в коде используют разные символы:

• // — однострочные в языках C, C++, PHP, C#, Java и JavaScript;
• # — однострочный в Python, PHP;
• /* */ — многострочные в C, C++, PHP, C#, Java, JavaScript.

Правила, которых принято придерживаться

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

1. Комментарии помещаются прямо над кодом, к которому они относятся. Так проще понять, о чём речь, не вникая в содержание каждой строчки. Совсем короткие пояснения можно писать справа.

# определяем общую структуру товара со значениями по умолчанию product = < "productId": 0, # идентификатор товара, по умолчанию: 0 "description": "", # описание товара, по умолчанию: пусто "categoryId": 0, # категория товара, по умолчанию: 0 "цена": 0,00 # цена, по умолчанию: 0,00 >

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

3. Пишут коротко и по делу. Комментарии без смысловой нагрузки страшно раздражают. Не нужно писать комментарии типа «это гениальный код», «таблица1», «! №; %:? *» и подобные.

4. Нельзя, чтобы комментарии оскорбляли кого-то или содержали слова, которые не поймёт технарь. В поддержку движения Black Lives Matter Twitter в своем коде решил не использовать слова slave, master и blacklist. Кто-то из россиян, возможно, улыбнётся, но стандарт есть стандарт.

Документирующие и поясняющие комментарии

В зависимости от того, для чего нужны комментарии, их условно делят на два вида:

• Поясняющие логику кода, использование алгоритмов. Разработчики применяют их на своё усмотрение.
• Документирующие — обязательные комментарии, содержащие информацию о назначении объектов, входных и выходных параметрах (если они есть), данные о разработчике и других важных вещах, относящихся к фрагменту кода. Они располагаются в заголовках модулей, библиотек, процедур и функций.

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

/** Класс-коннектор для обеспечения взаимодействия с сервером * Подключается через @link Socket> * посылает GET-запрос * использует @link ObjectInputStream> и @link ObjectOutputStream>. */ public class ServerConnector 

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

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

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

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

Например, документирующий комментарий из заголовка библиотеки Lodash для JavaScript выглядит так:

/** * @license * Lodash * Copyright OpenJS Foundation and other contributors * Released under MIT license * Based on Underscore.js 1.8.3 * Copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors */  

Кроме этого, в заголовочных комментариях к функциям указывают стандартный набор сведений:

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

Пример из той же библиотеки Lodash:

/** * Добавляет элементы `values` в `array`. * * @private * @param array Массив для изменения. * @param values Значения для добавления. * @returns Возвращает обработанный массив */ function arrayPush(array, values) < var index = -1, length = values.length, offset = array.length; while (++index < length) < array[offset + index] = values[index]; > return array; >

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

// Процедура запускает обработку очереди заданий. // // Параметры: // Настройки – Структура – настройки процедуры Процедура ЗапуститьОбработкуОчередиЗаданий (Настройки, БыстрыйРежим = Ложь)

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

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

В различных IDE есть возможность автоматизировать создание комментариев. Это делается с использованием тегов — дескрипторов, которые начинаются с символа @. Вот самые популярные:

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

Из таких комментариев автоматически формируется документация программы. Для этого используют генераторы документации, например, javadoc для языка Java, phpDocumentor для PHP, doxygen для C и C++, Epydoc для Pithon и другие.

Принцип работы прост. Генератор обрабатывает файл с исходным текстом, находит там имена классов, их членов, свойств, методов, процедур и функций, а затем связывает их с данными из наших комментариев с тегами. Из этой информации формируется документация в формате HTML, PDF, RTF или других.

При разработке библиотек и фреймворков обычно создается документация для API. Со временем она устаревает — в неё не успевают или просто забывают вносить изменения.

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

Когда нужны пояснения в коде, а когда — нет

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

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

/* Устанавливаем значение 32 для переменной age */ int age = 32;

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

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

def calculate_si_amount(principal, rate, time): interest = (principal*rate*time)/100 ## Проверить, когда сумма превысит 2000 ## if principal+interest > 2000: ## print(time) return principal+interest

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

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

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

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

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

/* не используйте глобальную функцию isFinite(), потому что она возвращает true, если параметр value не имеет значения */ Number.isFinite(value)

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

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

/* Рассчитываем стоимость товара */ cost = quantity * 2 * price;

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

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

/* Умножаем количество на 2, т.к. этот товар продается в паре */ cost = quantity * 2 * price;

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

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

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

Например, есть метод, который сравнивает числа a и b. Если a > b, он возвращает true, a если a < b — false:

public boolean max(int a, int b) < if(a > b) < return true; > else if(a == b) < return false; > else < return false; > >

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

public boolean max(int a, int b) < return a>b; >

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

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

Что в итоге

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

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

И помните, что комментарий — не панацея, он не спасёт плохой код, даже если сделает его понятнее. Сложные и запутанные фрагменты сокращайте и делайте рефакторинг, а комментируйте по минимуму.

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

Читайте также:

• Кирпичи для интернета: топ‑10 концепций современной веб‑архитектуры, которые вам точно нужно знать
• Как в СССР создавали полупроводниковый компьютер
• Что такое фреймворк и как выбрать фреймворк для фронтенда: советы бывалых

Quality Assurance дословно означает «обеспечение качества» — специалисты отвечающие за функциональное тестирование программного обеспечения на этапе разработки.

Агоритмический язык, который разработан и используется в ПО для управления оборудованием «Буран», «Морской старт», «Фрегат», «Протон-М» и других космических программ РФ.

Встроенный язык программирования, который используется в семействе программ «1С: Предприятие». Является интерпретируемым языком высокого уровня.

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

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

Интегрированная среда разработки, (Integrated development environment) — комплекс программных средств, используемый программистами для разработки программного обеспечения.

HTML — как закомментировать кусок кода

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

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

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

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

Просто комментарий в HTML

Самое главное, что комментарий будет виден только при открытии кода !

Заключение по комментариям HTML

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

Уверен статья выше помогла вам!

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