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

Без стека ~2 минуты 12

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

#TODO
#FIXME
#Warning
#Error
Как правильно применять теги

`#TODO`

Разработчики используют этот комментарий, чтобы указать на необходимость будущего рефакторинга. Комментарий #TODO позволяет обозначить, что именно нужно будет добавить в этой части кода и для чего это необходимо.

// TODO switch to the jest when it will works with modules

import expect from 'expect';
import chalk from 'chalk';

solutionSlice: {
      // TODO move counter to server
      startTime: Date.now(),
      processState: isFinished
        ? solutionStates.shown
        : solutionStates.notAllowedToShown,
      waitingTime,
    },

# TODO Move to custom validator
  validates :first_name, length: { maximum: 40 },
                         format: { with: UsefulRegexp.without_spec_chars },
                         allow_blank: true

Читайте также: Как читать чужой код: 6 правил, которые стоит помнить разработчику

`#FIXME`

Тег #FIXME показывает, что в этой части кода нужно что-то исправить. В некоторых случаях функциональность этого тега сливается с #TODO, поэтому #FIXME рекомендуется использовать, когда нужно указать на участок кода, от которого в будущем могут потенциально возникать проблемы.

# FIXME: Это нужно будет убрать, когда вернем аутентификацию для соцсетей
    user_from_session = get_session(conn, :current_user)

// FIXME: это хак с путями, надо перерабатывать их
      root: path.join(process.env.HEXLET_IDE_APP_DIR, '..'),

import/extensions: 0 # FIXME: remove when rule will be adjusted for new nodejs version

`#Warning`

По названию тега можно понять, что если перед кодом стоит такой комментарий с объяснением проблемы, то запускать такой код нужно очень аккуратно.

# Warning: The database defined as "test" will be erased and

`#Error`

Этот тег указывает на ошибку в коде — в комментарии разработчик может объяснить проблему и причину, почему ее не удалось решить. Обычно комментарий с таким тегом оставляют около участка кода, который совсем не запускается, либо не проходит тесты.

Как правильно применять теги

В каждой основной IDE есть плагины для работы с комментариями и их группировки. Например, в VS Code самый распространенный способ работы с такими комментариями — плагин Todo Tree, создающий дерево из групп комментариев для эффективной работы с ними.

В IDE от JetBrains комментарии #TODO и #FIXME автоматически определяются средой разработки в единые группы тегов. Подробнее об этом и том, как можно расширить функционал этой фичи на другие пользовательские комментарии, можно почитать на сайте JetBrains.

Напишите свое лучшее резюме У нас есть сервис Хекслет CV, где любой разработчик может опубликовать свое резюме и получить бесплатные комментарии от других программистов и HR-менеджеров, как его улучшить и что добавить к рекомендательному письму.