Перевод статьи «The Art of Writing Code Comments».
Не многие разработчики любят писать комментарии к коду. Более того, зачастую они не считают разумным тратить на это свое время. Если это про вас, надеюсь, что эта статья поможет вас переубедить.
Самая большая проблема при написании комментариев к коду заключается в том, что разработчики не видят в них ценности. А поскольку они не ощутили на собственном опыте, насколько полезными могут быть комментарии, они и не ценят само умение их писать.
Кроме того, не так просто убедить разработчиков научиться писать содержательные и осмысленные комментарии.
Некоторые лидеры мнений в среде разработчиков выступают за написание самопоясняющего кода. Имеется в виду, что ваш код должен быть написан таким образом, чтобы любой другой разработчик мог просто его прочесть и понять без всяких дополнительных примечаний. Для этого вы должны писать очень чистый код и, в частности, использовать описательные имена функций.
Но часто попросту невозможно создать на 100% читаемый код, потому что сложная логика требует более продвинутой архитектуры.
Если кто-то не может понять ваш код с первого прочтения, считается, что это сигнал о плохом качестве вашего кода. Должен сказать, что я не разделяю эту точку зрения.
Существует множество сценариев, в которых будет совсем неплохо добавить небольшой дополнительный контекст для коллег. Не говоря уже о начинающих разработчиках, которые не так хорошо знакомы с кодовой базой. Добавив комментарий с контекстом, вы им очень поможете, а вам это ничего не будет стоить и потребует совсем немного времени! Помимо всего прочего, комментарии в коде ускоряют процесс онбоардинга (введение в курс дела новичка в команде).
В этой статье мы рассмотрим следующие темы, связанные с искусством написания комментариев к коду:
- Зачем нужно указывать контекст в комментариях к коду
- Уровни комментирования кода
- Советы по написанию лучших комментариев к коду
- Оттачивание навыков комментирования кода
Зачем нужно указывать контекст в комментариях к коду
При написании комментариев к коду разработчики часто забывают о контексте, и совершенно зря! Контекст — это релевантная информация, которая поможет другому разработчику лучше понять код. Речь идет об информации, которую читатель не может получить непосредственно из самого кода.
Допустим, вы написали функцию под названием createNote, которая создает новый объект «note». Если мы добавим комментарий «Функция для создания нового объекта note», он будет бесполезен, потому что эту информацию разработчик может получить, просто читая код. Более того, это очень простая функция, создающая новые объекты. Она попросту не нуждается в дополнительных комментариях.
Предположим, мы используем более продвинутую функцию, созданную для шифрования при помощи с открытых и закрытых ключей. Здесь можно написать в комментариях кое-что полезное. Вы можете:
- объяснить, какой криптографический пакет используется
- объяснить, как функция преобразует ввод
- привести примеры использования этой функции и ожидаемых результатов.
Я большой поклонник добавления небольших примеров, показывающих ввод и вывод для сложных функций. Разработчикам, читающим ваш код, не придется его запускать, чтобы понять, как он работает: они все увидят на вашем примере, что значительно экономит время!
Какие типы комментариев к коду можно использовать?
Основных видов комментирования три. Есть много подходов, но они все равно попадают в какие-нибудь из трех категорий комментирования:
- на уровне документа
- на уровне функций
- на уровне логики.
Комментирование кода на уровне документа — это комментарии более общего типа. В них объясняются функции, которые вы найдете в документе. Помимо этого, вы можете добавить информацию об архитектуре или компоненте, в котором находится документ. Основная цель комментирования на уровне документа — добавление высокоуровневой информации о вашем коде.
Наиболее полезный тип комментариев — на уровне функций. Здесь целью является добавление контекста к функциям. При этом очень важно не злоупотреблять комментариями, потому что многие функции не требуют пояснений. Добавляйте примечания только к функциям, требующим дополнительного контекста, чтобы ускорить обучение других разработчиков.
Наконец, вы можете использовать самый низкий уровень комментирования — на уровне логики. Такие комментарии предназначены для пояснения сложных фрагментов кода. Учитывайте, что они могут быстро раздуть ваш код и ухудшить читаемость, поэтому используйте их только для сложных путей кода.
Советы по написанию комментариев к коду
Как упоминалось ранее, контекст играет очень важную роль, в том числе и при комментировании кода! Спросите себя, почему вы решили проблему именно так, как решили. Этот вопрос поможет вам лучше описать ваш код и добавить ценный контекст.
Важно писать комментарии одновременно с кодом. Когда вы активно работаете над кодом, вам гораздо проще уловить контекст. Многие разработчики предпочитают полностью закончить свой код, а затем добавлять комментарии. И часто эти комментарии оказываются менее точными и менее ценными именно из-за отсутствия контекста.
Не злоупотребляйте комментариями к коду. Добавление большого количества комментариев сделает ваш код громоздким, из-за чего читателю будет сложно в нем разобраться. Не каждая функция требует дополнительных разъяснений. Добавлять контекст стоит к наиболее ценным функциям, например, содержащим важную бизнес-логику.
Никто не скажет вам совершенно точно, где оставлять комментарий, а где нет: идеальный баланс нужно искать самостоятельно.
Наконец, многие языки предлагают best practices или стандарты комментирования кода. Например, JSDoc — популярный стандарт комментирования в сообществе JavaScript. Кроме того, стандарт JSDoc понимают многие IDE, благодаря чему в них можно оставлять дополнительные пояснения при написании кода. Например, можно объяснять тип переменной и ее использование при передаче ее функции.
/**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {
// code
}
Вот как IDE (в данном случае — Visual Studio Code) автоматически отображает эту информацию.
Дополнительный плюс использования JSDoc — большинству разработчиков он понятен. Это общий язык для быстрой передачи информации и контекста о коде или отдельной функции.
Оттачивание навыков комментирования кода
Разработчики любят давать обратную связь в процессе ревью кода. Однако не многие утруждают себя проверкой качества комментариев к коду. Обязательно обращайте внимание на комментарии к коду ваших коллег и давайте им фидбэк на этот счет. Можно начать с пометки бесполезных комментариев, не добавляющих никакого контекста. Это отличное упражнение поможет научиться определять, что важно, а что — нет.
Помимо этого можно создать дополнительный пункт, касающийся комментариев, в чеклисте «Готово» для проверки пул-реквестов.
Также, если хотите улучшить свои навыки написания комментариев, попробуйте поискать популярные репозитории GitHub и ознакомиться с их стилем комментирования. Это отличный способ узнать, как другие разработчики подходят к комментированию своего кода.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]
