Сегодня затронем еще одну тему, которая в сообществе разработчиков всегда вызывает бурные обсуждения. Поговорим о документации и комментировании кода: насколько это необходимо и каких правил стоит придерживаться.
Для начала разберемся, чем отличается документация от комментария в коде.
▫️Документация — это характеристика конкретного объекта, класса, метода, описание его назначения, параметров и механики работы. Оформляется в коде через
///. Например, возьмем школьную задачку — надо написать метод, который по значениям катетов прямоугольного треугольника будет рассчитывать значение гипотенузы.
/// Метод для вычисления гипотенузы по известным значениям
/// катетов прямоугольного треугольника
///
/// Принимает:
/// - [firstLeg] - первый катет прямоугольного треугольника
/// - [secondLeg] - второй катет прямоугольного треугольника
double calculateHypotenuse(double firstLeg, double secondLeg) {
final hypotenuse = sqrt(firstLeg * firstLeg + secondLeg * secondLeg);
return hypotenuse;
}
Если мы добавим этот пример в любую IDE, при наведении мышью на метод будет высвечиваться наша добавленная документация. При этом специальные знаки помогают удобно форматировать описание. Например, квадратные скобки позволяют обозначить параметр, а дефисы — организовать маркированный список.
▫️Комментарий — это обычное словесное описание алгоритма действий. Если в коде встречается сложный участок, где логика не совсем очевидна, или имеются какие-то важные сведения, которые разработчик хочет передать своим коллегам и себе в будущее, оформлять их стоит именно как комментарий. Они выделяются с помощью
//. Как показывает практика, и документация, и комметрирование кода — очень удобные инструменты, которые позволяют сделать проект максимально понятным и простым для вхождения новых разработчиков.
Так почему же тема холиварная?
В первую очередь потому что зачастую и документация, и комментарии в проекте не систематизированы, оформляются хаотично, чем только мешают и запутывают. Разработчики из-за этих проблем не видят в них никакой пользы, только лишь дополнительную трату времени.
Как это исправить?
Поможет соответствие ряду правил.
1. Зафиксировать в проекте порядок комментирования и документации кода.
Очень удобно на уровне всей команды заранее определить шаблоны. В будущем это позволит держать весь проект в едином формате.
2. Думать о том, как этот участок кода может восприниматься другими разработчиками или тобой через большой промежуток времени.
В больших проектах, которые разрабатываются и поддерживаются долгое время, не стоит полагаться на свою память или память коллег. Нюансы имеют свойство забываться, разработчики могут менять проекты и место работы, поэтому полезно фиксировать сложные места сразу.
3. Не комментировать лишнее.
Такая ошибка часто встречается, что вызывает негатив к комментированию в целом. Важно покрывать комментариями только то, что действительно нуждается в пояснении. Например, переменные с говорящими названиями или простые условия в блоке if описывать смысла нет.
4. Больше текста — не значит лучше.
Документация и комментарии должны быть емкими, простыми для восприятия. Если текста будет слишком много, вероятность, что его будут пропускать, увеличивается.
💬Делитесь своим опытом и лучшими практиками в комментариях.