Комментарии в коде: почему, зачем и как? | OTUS
⚡ Подписка на курсы OTUS!
Интенсивная прокачка навыков для IT-специалистов!
Подробнее

Курсы

Программирование
Python Developer. Professional
-3%
Разработчик на Spring Framework
-5%
iOS Developer. Professional
-8%
Golang Developer. Professional
-6%
Базы данных
-12%
Agile Project Manager
-5%
Android Developer. Professional
-11%
Microservice Architecture
-5%
C++ Developer. Professional
-5%
Highload Architect
-6%
JavaScript Developer. Basic
-8%
Backend-разработчик на PHP
-9%
Разработчик IoT
-13%
PostgreSQL
-8%
Алгоритмы и структуры данных Разработчик программных роботов (RPA) на базе UiPath и PIX Unity Game Developer. Basic Разработчик голосовых ассистентов и чат-ботов Vue.js разработчик VOIP инженер NoSQL Супер-практикум по использованию и настройке GIT Symfony Framework iOS Developer. Basic Супер-интенсив «СУБД в высоконагруженных системах» Супер-интенсив "Tarantool"
Инфраструктура
DevOps практики и инструменты
-12%
Базы данных
-12%
Network engineer. Basic
-10%
Network engineer
-4%
Экcпресс-курс «ELK»
-10%
Инфраструктурная платформа на основе Kubernetes
-6%
Administrator Linux.Basic
-10%
Экспресс-курс «CI/CD или Непрерывная поставка с Docker и Kubernetes»
-30%
Дизайн сетей ЦОД
-13%
PostgreSQL
-8%
Разработчик программных роботов (RPA) на базе UiPath и PIX Reverse-Engineering. Professional Внедрение и работа в DevSecOps Administrator Linux. Advanced Infrastructure as a code in Ansible Супер - интенсив по паттернам проектирования Супер - интенсив по Kubernetes Экспресс-курс «IaC Ansible»
Специализации Курсы в разработке Подготовительные курсы
+7 499 938-92-02

Комментарии в коде: почему, зачем и как?

JavaDeep_20_06_Site.png

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

Начнём с того, что такое комментарий. Комментарий – текст, который есть в коде, но который игнорирует компилятор. В байткоде комментариев нет. Таким образом, комментарии чем-то сродни форматированию. Все наши выравнивания, отступы и переносы строк компилятору не интересны. И форматирование и комментарии помогают читать код, не являясь его частью.

Здесь уже можно сделать первый важный вывод

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

Почему без комментария непонятно? Слишком сложное решение? Неявная зависимость? Преждевременная оптимизация?

Лучшая документация к коду – сам код

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

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

«Ничего не стали придумывать своего, а взяли алгоритм из третьего тома Кнута (мой вольный перевод)...»

И сразу все становится понятно

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

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

В качестве заключения

Отметим отдельный вид комментария – аннотации. Да, на мой взгляд, это тоже комментарий. С очень строгим форматированием. И даже с возможностью найти их в байткоде (если соответствующим образом настроить). Но при этом со всем атрибутами комментария: аннотации бессмысленны, если их никто не читает, код должен быть понятен и без аннотаций, следует придерживаться «полиси» по использованию и созданию аннотаций.

Есть вопрос? Напишите в комментариях!

Не пропустите новые полезные статьи!

Спасибо за подписку!

Мы отправили вам письмо для подтверждения вашего email.
С уважением, OTUS!

Автор
0 комментариев
Для комментирования необходимо авторизоваться