Как правильно писать комментарии к коду: несколько важных примеров

На нескольких простых примерах разбираем, как писать понятные комментарии в коде и для чего их группировать.
#TODO
Разработчики используют этот комментарий, чтобы указать на необходимость будущего рефакторинга. Комментарий #TODO
позволяет обозначить, что именно нужно будет добавить в этой части кода и для чего это необходимо.
Читайте также:
Как читать чужой код: 6 правил, которые стоит помнить разработчику
#FIXME
Тег #FIXME
показывает, что в этой части кода нужно что-то исправить. В некоторых случаях функциональность этого тега сливается с #TODO
, поэтому #FIXME
рекомендуется использовать, когда нужно указать на участок кода, от которого в будущем могут потенциально возникать проблемы.
#Warning
По названию тега можно понять, что если перед кодом стоит такой комментарий с объяснением проблемы, то запускать такой код нужно очень аккуратно.
#Error
Этот тег указывает на ошибку в коде — в комментарии разработчик может объяснить проблему и причину, почему ее не удалось решить. Обычно комментарий с таким тегом оставляют около участка кода, который совсем не запускается, либо не проходит тесты.
Как правильно применять теги
В каждой основной IDE есть плагины для работы с комментариями и их группировки. Например, в VS Code самый распространенный способ работы с такими комментариями — плагин Todo Tree, создающий дерево из групп комментариев для эффективной работы с ними.
В IDE от JetBrains комментарии #TODO
и #FIXME
автоматически определяются средой разработки в единые группы тегов. Подробнее об этом и том, как можно расширить функционал этой фичи на другие пользовательские комментарии, можно почитать на сайте JetBrains.
Напишите свое лучшее резюме
У нас есть сервис Хекслет CV, где любой разработчик может опубликовать свое резюме и получить бесплатные комментарии от других программистов и HR-менеджеров, как его улучшить и что добавить к рекомендательному письму.
Svet Ivanov
3 года назад