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

Курсы

Программирование
iOS Developer. Basic
-23%
Python Developer. Professional
-13%
Golang Developer. Professional
-17%
Python Developer. Basic
-16%
iOS Developer. Professional
-13%
C# ASP.NET Core разработчик
-18%
Unity Game Developer. Professional
-11%
React.js Developer
-12%
Android Developer. Professional
-7%
Software Architect
-12%
C++ Developer. Professional
-8%
Разработчик C#
-8%
Backend-разработчик на PHP
-8%
Архитектура и шаблоны проектирования
-12%
Программист С Разработчик на Spring Framework MS SQL Server Developer AWS для разработчиков Cloud Solution Architecture Разработчик голосовых ассистентов и чат-ботов Vue.js разработчик VOIP инженер Нереляционные базы данных Супер - интенсив по паттернам проектирования Супер-практикум по использованию и настройке GIT IoT-разработчик Advanced Fullstack JavaScript developer Супер-интенсив Azure
Инфраструктура
Мониторинг и логирование: Zabbix, Prometheus, ELK
-17%
DevOps практики и инструменты
-18%
Архитектор сетей
-21%
Инфраструктурная платформа на основе Kubernetes
-22%
Супер-интенсив «IaC Ansible»
-16%
Супер-интенсив по управлению миграциями (DBVC)
-16%
Administrator Linux. Professional
-5%
Administrator Linux.Basic
-10%
Супер-интенсив «ELK»
-10%
Базы данных Сетевой инженер AWS для разработчиков Cloud Solution Architecture Разработчик голосовых ассистентов и чат-ботов Внедрение и работа в DevSecOps Супер-практикум по работе с протоколом BGP Супер - интенсив по паттернам проектирования Супер - интенсив по Kubernetes Супер-интенсив «СУБД в высоконагруженных системах»
Специализации Курсы в разработке Подготовительные курсы
+7 499 938-92-02

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

JavaDeep_20_06_Site.png

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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