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

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

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

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

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

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

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

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

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

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

Комментарии

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

Обычно мы их используем, чтобы описать, как и почему работает код.

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

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

Новички склонны использовать комментарии, чтобы объяснять, «что делает код». Например, так:

// Этот код делает это (. ) и вот это (. ) // . и кто знает, что ещё. очень; сложный; код;

Но в хорошем коде количество «объясняющих» комментариев должно быть минимальным. Серьёзно, код должен быть таким, чтобы его можно было понять без комментариев.

Про это есть хорошее правило: «Если код настолько запутанный, что требует комментариев, то, может быть, его стоит переделать?»

Рецепт: выносите код в функции

Иногда выгодно заменить часть кода функцией, например, в таком случае:

function showPrimes(n) < nextPrime: for (let i = 2; i < n; i++) < // проверяем, является ли i простым числом for (let j = 2; j < i; j++) < if (i % j == 0) continue nextPrime; >alert(i); > >

Лучший вариант – использовать отдельную функцию isPrime :

function showPrimes(n) < for (let i = 2; i < n; i++) < if (!isPrime(i)) continue; alert(i); >> function isPrime(n) < for (let i = 2; i < n; i++) < if (n % i == 0) return false; >return true; >

Теперь код легче понять. Функция сама становится комментарием. Такой код называется самодокументированным.

Рецепт: создавайте функции

И если мы имеем такой длинный кусок кода:

// здесь мы добавляем виски for(let i = 0; i < 10; i++) < let drop = getWhiskey(); smell(drop); add(drop, glass); >// здесь мы добавляем сок for(let t = 0; t < 3; t++) < let tomato = getTomato(); examine(tomato); let juice = press(tomato); add(juice, glass); >// . 

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

addWhiskey(glass); addJuice(glass); function addWhiskey(container) < for(let i = 0; i < 10; i++) < let drop = getWhiskey(); //. >> function addJuice(container) < for(let t = 0; t < 3; t++) < let tomato = getTomato(); //. >>

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

В реальности мы не можем полностью избежать «объясняющих» комментариев. Существуют сложные алгоритмы. И есть хитрые уловки для оптимизации. Но в целом мы должны стараться писать простой и самодокументированный код.

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

Итак, обычно «объясняющие» комментарии – это плохо. Но тогда какой комментарий считается хорошим?

Описывайте архитектуру Сделайте высокоуровневый обзор компонентов, того, как они взаимодействуют, каков поток управления в различных ситуациях… Если вкратце – обзор кода с высоты птичьего полёта. Существует специальный язык UML для создания диаграмм, разъясняющих архитектуру кода. Его определённо стоит изучить. Документируйте параметры и использование функций Есть специальный синтаксис JSDoc для документирования функций: использование, параметры, возвращаемое значение.

/** * Возвращает x, возведённое в n-ную степень. * * @param x Возводимое в степень число. * @param n Степень, должна быть натуральным числом. * @return x, возведённое в n-ную степень. */ function pow(x, n)

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

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

Также существуют инструменты, например, JSDoc 3, которые умеют генерировать HTML-документацию из комментариев. Получить больше информации о JSDoc вы можете здесь: https://jsdoc.app.

Почему задача решена именно таким способом?

Важно то, что написано. Но то, что не написано, может быть даже более важным, чтобы понимать происходящее. Почему задача решена именно этим способом? Код не даёт ответа.

Если есть несколько способов решить задачу, то почему вы выбрали именно этот? Особенно если ваш способ – не самый очевидный.

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

1. Вы (или ваш коллега) открываете написанный некоторое время назад код и видите, что в нём есть, что улучшить.
2. Вы думаете: «Каким глупым я раньше был и насколько умнее стал сейчас», и переписываете его на «более правильный и оптимальный» вариант.
3. …Желание переписать код – это хорошо. Но в процессе вы понимаете, что «оптимальное» решение на самом деле не такое уж и оптимальное. Вы даже смутно припоминаете, почему, так как в прошлый раз вы уже его пробовали. Вы возвращаетесь к правильному варианту, потратив время зря.

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

В коде есть какие-то тонкости? Где они используются?

Если в коде есть какие-то тонкости и неочевидные вещи, его определённо нужно комментировать.

Итого

Комментарии – важный признак хорошего разработчика, причём как их наличие, так и отсутствие.

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

Комментируйте:

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

Избегайте комментариев:

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

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

Урок №9. Комментарии

Комментарий — это строка (или несколько строк) текста, которая вставляется в исходный код для объяснения того, что делает код. В языке C++ есть 2 типа комментариев: однострочные и многострочные.

Оглавление:

1. Однострочные комментарии
2. Многострочные комментарии
3. Как правильно писать комментарии?
4. Закомментировать код

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

Однострочные комментарии — это комментарии, которые пишутся после символов // . Они пишутся в отдельных строках и всё, что находится после этих символов комментирования, — игнорируется компилятором, например:

std :: cout

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

std :: cout << « Hello , world ! » << std :: endl ; // cout и endl находятся в библиотеке iostream std :: cout << « It is so exciting ! » << std :: endl ; // эти комментарии усложняют чтение кода std :: cout << « Yeah ! » << std :: endl ; // особенно, когда строки разной длины

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

// cout и endl находятся в библиотеке iostream
std :: cout << « Hello , world ! » << std :: endl ; // теперь уже легче читать std :: cout << « It is so exciting ! » << std :: endl ; std :: cout << « Yeah ! » << std :: endl ;

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

Многострочные комментарии — это комментарии, которые пишутся между символами /* */ . Всё, что находится между звёздочками, — игнорируется компилятором:

/* Это многострочный комментарий.
Эта строка игнорируется
и эта тоже. */

Так как всё, что находится между звёздочками, — игнорируется, то иногда вы можете наблюдать следующее:

/* Это многострочный комментарий.
* Звёздочки слева
* упрощают чтение текста

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

/* Это многострочный /* комментарий */ а это уже не комментарий * /
// Верхний комментарий заканчивается перед первым */, а не перед вторым */

Правило: Никогда не используйте вложенные комментарии.

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

Во-первых, на уровне библиотек/программ/функций комментарии отвечают на вопрос «ЧТО?»: «Что делают эти библиотеки/программы/функции?». Например:

// Эта программа вычисляет оценку студента за семестр на основе его оценок за модули
// Эта функция использует метод Ньютона для вычисления корня функции
// Следующий код генерирует случайное число

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

Во-вторых, внутри библиотек/программ/функций комментарии отвечают на вопрос «КАК?»: «Как код выполняет задание?». Например:

/* Для расчета итоговой оценки ученика, мы складываем все его оценки за уроки и домашние задания,
а затем делим получившееся число на общее количество оценок.
Таким образом, мы получаем средний балл ученика. */
// Чтобы получить рандомный (случайный) элемент, мы выполняем следующее:
// 1) Составляем список всех элементов.
// 2) Вычисляем среднее значение для каждого элемента, исходя из его веса, цвета и цены.
// 3) Выбираем любое число.
// 4) Определяем соответствие элемента случайно выбранному числу.
// 5) Возвращаем случайный элемент.

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

В-третьих, на уровне стейтментов (однострочного кода) комментарии отвечают на вопрос «ПОЧЕМУ?»: «Почему код выполняет задание именно так, а не иначе?». Плохой комментарий на уровне стейтментов объясняет, что делает код. Если вы когда-нибудь писали код, который был настолько сложным, что нужен был комментарий, который бы объяснял, что он делает, то вам нужно было бы не писать комментарий, а переписывать этот код.

Примеры плохих и хороших однострочных комментариев:

// Присваиваем переменной sight значение 0

(По коду это и так понятно)

// Игрок выпил зелье слепоты и ничего не видит

(Теперь мы знаем, ПОЧЕМУ зрение у игрока равно нулю)

// Рассчитываем стоимость элементов
cost = items / 2 * storePrice ;

(Да, мы видим, что здесь подсчет стоимости, но почему элементы делятся на 2?)

// Нам нужно разделить все элементы на 2, потому что они куплены по парам
cost = items / 2 * storePrice ;

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

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

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

Подытожим:

На уровне библиотек/программ/функций оставляйте комментарии, отвечая на вопрос «ЧТО?».

Внутри библиотек/программ/функций оставляйте комментарии, отвечая на вопрос «КАК?».

На уровне стейтментов оставляйте комментарии, отвечая на вопрос «ПОЧЕМУ?».

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

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

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

std :: cout << 1 ; // std::cout << 1;

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

std :: cout << 1 ; std :: cout << 2 ; std :: cout << 3 ;

Закомментировано символами однострочного комментария:

// std::cout << 1; // std::cout << 2; // std::cout << 3;

Закомментировано символами многострочного комментария:

std::cout << 1; std::cout << 2; std::cout << 3;

Есть несколько причин, почему следует использовать «закомментирование»:

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

Причина №2: Вы написали код, который компилируется, но работает не так, как нужно и сейчас у вас нет времени с этим возиться. Закомментируйте код, а затем, когда будет время, исправьте ошибки.

Причина №3: Поиск корня ошибки. Если вас не устраивают результаты работы программы (или вообще происходит сбой), полезно будет поочерёдно «отключать» части вашего кода, чтобы понять какие из них рабочие, а какие — создают проблемы. Если вы закомментируете одну или несколько строчек кода и программа начнет корректно работать (или пропадут сбои), шансы того, что последнее, что вы закомментировали, является ошибкой — очень велики. После этого вы сможете разобраться с тем, почему же этот код не работает так, как нужно.

Причина №4: Тестирование нового кода. Вместо удаления старого кода, вы можете его закомментировать и оставить для справки, пока не будете уверены в том, что ваш новый код работает так, как нужно. Как только вы будете уверены в новом коде, то сможете без проблем удалить старые фрагменты кода. Если же новый код у вас будет работать не так, как нужно, то вы сможете его удалить и откатиться к старому коду.

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

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

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

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

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

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

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

// Программа,которую нужно выполнить,чтобы стать программистом 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) — комплекс программных средств, используемый программистами для разработки программного обеспечения.