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

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

Комментарии – способ прокомментировать код на ходу, на той же строке. Вот пример кода. Здесь, “Получил пользователя” – это комментарий.

user = get_user_by_id(...) # Получил пользователя 

Такие комментарии начинаются с символа # . Можно добавить комментарий на отдельной строке:

# Получил пользователя user = get_user_by_id(...) 

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

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

 # Получил пользователя # user = get_user_by_id(. ) 

Докстринги

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

def tensorsolve(a, b, axes=None): """ Solve the tensor equation ``a x = b`` for x. It is assumed that all indices of `x` are summed over in the product, together with the rightmost indices of `a`, as is done in, for example, ``tensordot(a, x, axes=len(b.shape))``. """ 

В серьёзных проектах из них часто генерируется документация, поэтому они могут быть большими, по несколько экранов. Это касается проектов, у которых есть документация для разработчиков: Django, numpy, sqlalchemy.

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

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

Как не использовать

Дублировать информацию из кода

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

# загружаем данные из файла data.json with open('users.json', 'r') as handler: data = json.load(handler) 

Вот как можно исправить:

with open('users.json', 'r') as handler: data = json.load(handler) 

А так – ещё лучше:

data = load_all_users_from_file() 

Не поддерживать комментарии

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

# загружаем данные из файла data.json data = db_session.query(User).all() 

Данные из файла? WAT?

Думать, что все поймут

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

inv(strain_tensor) - rigidity.T # правый случай 

Правый, правда? Ну, теперь всё понятно.

Шутить

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

Как использовать

Вот хорошие причины использовать комментарии:

• объяснить неочевидное поведение: бывает, что нужно объяснить какой-нибудь подводный камень куска кода или объяснить поведение в особом случае; использовать только если ту же информацию в коде поселить нельзя или очень сложно;
• оставить напоминание себе или коллеге: речь про комментарии вроде TODO: кешировать ответ ручки или FIXME: учитывать часовой пояс .

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

Что изучать

• Доклад Григория Петрова про комментирование исходников. Обязателен к просмотру.
• PEP 257. ПЕП про докстринги.
• doctest. Документация к модулю про доктесты.
• What is the best comment in source code you have ever encountered?. Шутить в коде не стоит, а вот посмеяться с чужих шуток можно. Это ж не нам поддерживать.

Попробуйте бесплатные уроки по Python

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

Переходите на страницу учебных модулей «Девмана» и выбирайте тему.

Java: Комментарии

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

Комментарии в Java бывают трех видов:

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

// For Winterfell! 

Также комментарий может находиться на строке после какого-нибудь кода:

System.out.println("I am the King"); // => For Lannisters! 

/* * The night is dark and * full of terrors. */ System.out.println("I am the King"); // => I am the King 

Задание

Создайте однострочный комментарий с текстом: You know nothing, Jon Snow!.

Упражнение не проходит проверку — что делать? ��

Если вы зашли в тупик, то самое время задать вопрос в «Обсуждениях». Как правильно задать вопрос:

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

В моей среде код работает, а здесь нет ��

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

Мой код отличается от решения учителя ��

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

В редких случаях бывает, что решение подогнано под тесты, но это видно сразу.

Прочитал урок — ничего не понятно ��

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

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

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

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

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

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

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

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

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

Без JavaScript будущему разработчику никуда. Записывайтесь на профессиональный курс по JavaScript первого уровня, проходящий c 13 февраля по 15 апреля 2024. До 10 ноября цена 25 900 ₽ 30 900 ₽

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

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

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

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

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

Не надо писать очевидные комментарии в коде:

// Обновляем состояние на успешное setState(< success: true >);

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

Называйте правильно

Чтобы сократить число комментариев в коде пишите понятные названия методов, переменных или классов:

// Получение пользователя по его идентификатору get(i: number)

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

getUserById(id: number)

Предметная область

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

/* @summary Идентификатор подписанта докумена */ signerId: number

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

Контракты

Если вы описываете контракты на стыке между front и backend или микросервисами, то свойства передаваемого объекта лучше пояснять, если эту функцию не выполнять swagger. Так вы облегчите интеграцию между частями системы, особенно если команда не состоит из одного человека ��

export class ImageRequirement < /** @summary Формат изображения для генерации */ @IsEnum(ImageType) format: ImageType; >

Не очевидные вещи

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

/* На текущий момент мы по умолчанию ставим что * все платежи проверены, пока в ТЗ (. ) не внесен * алгоритм валидации платежей */ getPayments(paymentId: number, isValidated: boolean = true)

Интеграции с внешними сервисами

Если ваш сервис интегрируется с внешними API, то все запросы и ответы лучше всего так же покрывать @summary для расшифровки, а то не все внешние сервисы имеют понятные контракты взаимодействия. Особенно стоит обратить внимание на числовые статусы, которые может вернуть сервис:

enum PayApiStatus < /** @summary если платёж принят, но не выполнен */ Accepted = 1 >

TODO

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

// TODO: Доделать часть отправки уведомления

Я например использую ToDo Tree.

Документация

Если вы пользуетесь генератором документации на основании кода, тогда вы можете дополнительно включать @summary или @returns для включения в доку:

/** * Генерация изображений * @summary * Метод позволяет получить нарезку изображений нужного формата jpg, png, webp с указанной шириной и высотой. * При генерации изображения сервис ориентируется на высоту как ограничивающий параметр. * @returns GenerateImages.Response - Те же требования в каждый из которых добавлено созданное изображение, * а так же исходное изображение. Если оно было трансформировано, то в данных к этому изображению * будут параметры изображения после трансформации. */ generateImages(. )

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

Итог

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