Комментарии в коде: почему, зачем и как?
Давайте сегодня попробуем разобраться: когда комментарии полезны, когда вредны, когда нужно вводить правила написания комментариев и когда вместо комментария лучше использовать аннотации.
Начнём с того, что такое комментарий. Комментарий – текст, который есть в коде, но который игнорирует компилятор. В байткоде комментариев нет. Таким образом, комментарии чем-то сродни форматированию. Все наши выравнивания, отступы и переносы строк компилятору не интересны. И форматирование и комментарии помогают читать код, не являясь его частью.
Здесь уже можно сделать первый важный вывод
Комментарий не имеет смысла, если его не прочтут или не поймут при прочтении. При этом, конечно, само наличие комментария, даже совсем непонятного, это сигнал тому, кто смотрит код. Сигнал, что здесь происходит что-то важное. Это важное напрямую из кода понять нельзя и поэтому оставлен комментарий. Это второй момент, на который следует обратить внимание, когда пишете комментарии.
Почему без комментария непонятно? Слишком сложное решение? Неявная зависимость? Преждевременная оптимизация?
Лучшая документация к коду – сам код
Если из кода непонятно, что код делает, это очень тревожный сигнал. Комментарии скорее всего не помогут. И в тоже время комментарии в формате javadoc очень удобны и полезны в разработке. По своей задумке они не раскрывают ничего нового о классах и методах, которые описывают, а являются документацией. То же самое делает код, но в более удобном для чтения формате.
Например, если вы знакомы с алгоритмами получения случайных чисел, вы поймете код класса Random. Но согласитесь, приятно в документации к классу увидеть:
«Ничего не стали придумывать своего, а взяли алгоритм из третьего тома Кнута (мой вольный перевод)...»
И сразу все становится понятно
Вот мы и затронули тему форматирования комментариев. В javadoc формат довольно строгий для того, чтобы по этим комментариям можно было сделать документацию. В разных проектах можно встретить разные «полиси» для комментариев.
Если все комментарии оформлены одинаково и в заранее понятных участках кода, их проще писать и читать. Если разработчики языка не предложили нам никакой структуры комментариев, добавим её сами.
В качестве заключения
Отметим отдельный вид комментария – аннотации. Да, на мой взгляд, это тоже комментарий. С очень строгим форматированием. И даже с возможностью найти их в байткоде (если соответствующим образом настроить). Но при этом со всем атрибутами комментария: аннотации бессмысленны, если их никто не читает, код должен быть понятен и без аннотаций, следует придерживаться «полиси» по использованию и созданию аннотаций.
Есть вопрос? Напишите в комментариях!
