Vue: добавление комментариев | html

Добавил(а) microsin

В модулях компонентов Vue (файлы *.vue) имеются 3 варианта секций кода [1]:

< script setup>< /script> для JavaScript.
< template>< /template> для HTML.
< style scoped>< /style> для стилей CSS.

Если кратко, то особенности комментирования в Vue следующие:

Место	Синтаксис	Пример
< script>	`//` или `/* */`	`// JS комментарий`
< template>	`< !-- -->`	`< !-- Комментарий -->`
< style>	`/* */`	`/* CSS комментарий */`

Давайте рассмотрим каждую секцию более подробно.

[Комментарий внутри script setup]

В секции < script setup> компонента Vue используются стандартные JavaScript-комментарии. Вот как правильно их оформлять:

1. Однострочные комментарии (`//`):

< script setup>
import { ref, onMounted, watch } from 'vue'
import { useWebSocketStore } from '@/stores/webSocketStore.js'

// Хранилище WebSocket соединения
const webSocketStore = useWebSocketStore()

// Реактивные данные
const settings = ref({}) // Объект настроек устройства
const isLoading = ref(false) // Флаг загрузки

// Этот хук выполняется при монтировании компонента
onMounted(() => {
  // Подключаемся к WebSocket серверу
  webSocketStore.connect('ws://localhost:8080')
})
< /script>

2. Многострочные комментарии (`/* */`):

< script setup>
/*
 * SettingsView.vue
 * Компонент для отображения и редактирования настроек
 *
 * Основные функции:
 * 1. Загрузка настроек через WebSocket
 * 2. Редактирование параметров
 * 3. Отправка команд устройству
 *
 * Автор: [Ваше имя]
 * Версия: 1.0.0
 */

import { ref } from 'vue'

/*
 * Это большой блок комментариев, который можно использовать
 * для документации сложных функций или конфигураций.
 *
 * Например, описание структуры объекта settings:
 * {
 *   fields: Array< Field>, // массив полей настроек
 *   timestamp: string,    // время последнего обновления
 *   device_id: string     // идентификатор устройства
 * }
 */

const settings = ref({})
< /script>

3. JSDoc-комментарии (для автодокументирования):

< script setup>
/**
 * Загружает настройки с устройства через WebSocket
 * @async * @function loadSettings
 * @returns {Promise< void>}
 * @throws {Error} При ошибке подключения или таймауте
 */
async function loadSettings() {
  try {
    // ... реализация
  } catch (error) {
    console.error('Ошибка загрузки настроек:', error)
  }
}

/**
 * Отправляет обновлённое значение параметра на устройство
 * @param {Event} event - Событие изменения input/select
 * @param {string} event.target.value - Новое значение
 * @param {string} event.target.dataset.field - Идентификатор поля
 */
function settings_write(event) {
  if (!event) return

  const param_value = event.target.value
  const field_id = event.target.dataset.field

  // Валидация значения
  if (isValidValue(param_value)) {
    const json = JSON.stringify({
      command: 'write',
      param: field_id,
      value: param_value
    })
    webSocketStore.sendMessage(json)
  }
}

/**
 * Вспомогательная функция для валидации
 * @private
 * @param {*} value - Проверяемое значение
 * @returns {boolean} - true если значение валидно
 */
function isValidValue(value) {
  return value !== null && value !== undefined && value !== ''
}
< /script>

Советы по комментированию:

1. Комментируйте сложную логику, а не очевидные вещи.

2. Используйте JSDoc для публичных функций.

3. Добавляйте TODO комментарии для запланированных улучшений:

   // TODO: Добавить кэширование настроек в localStorage
   // FIXME: Исправить утечку памяти при частых переподключениях
   // HACK: Временное решение, нужно переделать

4. Удаляйте закомментированный код перед коммитом.

5. Используйте английский для комментариев в интернациональных проектах.

[Комментарий внутри template]

В Vue.js шаблонах (тег < template>) можно использовать только HTML-комментарии < !-- -->.

Правильные комментарии в < template>:

< template>
  < !-- Главный контейнер приложения -->
  < div class="container">

    < !-- Шапка с навигацией -->
    < header class="header">
      < h1>Моё приложение< /h1>
    < /header>

    < !-- Основной контент -->
    < main class="content">
      < !-- Условный рендеринг -->
      < div v-if="isLoading">
        < !-- Индикатор загрузки -->
        < div class="spinner">Загрузка...< /div>
      < /div>

      < !-- Основные данные -->
      < div v-else>
        < !-- Отображение списка пользователей -->
        < ul>
          < li v-for="user in users" :key="user.id">
            {{ user.name }} < !-- Имя пользователя -->
          < /li>
        < /ul>
      < /div>

      < !--
        Многострочный комментарий
        для сложных блоков кода
      -->
      < div class="footer">
        < !-- Кнопка сохранения: отправляет данные на сервер -->
        < button @click="saveData">Сохранить< /button>
      < /div>
    < /main>
  < /div>
< /template>

Что НЕ работает в < template>:

1. JavaScript комментарии:

   < template>
     // Это не сработает
     /* Это тоже не сработает */
   < /template>

2. CSS комментарии внутри тегов:

   < template>
     < style>/* Это будет проигнорировано */< /style>
     < div class="class /* и это */">< /div>
   < /template>

Важные моменты:

1. Комментарии удаляются при сборке — они не попадают в итоговый HTML.

2. Нельзя комментировать директивы:

   < !-- Неправильно -->
   < !-- < div v-if="isVisible"> -->
     Контент
   < !-- < /div> -->

   < !-- Правильно -->
   < div v-if="isVisible">
     < !-- Условно отображаемый контент -->
     Контент
   < /div>

3. Для временного отключения кода лучше использовать `v-if="false"`:

   < div v-if="false">
     < !-- Этот блок не будет отображаться -->
     < button @click="oldMethod">Устаревшая кнопка< /button>
   < /div>

[Комментарий в теге стилей style scoped]

В теге < style scoped> Vue-компонента можно использовать стандартные CSS-комментарии. Однако, из-за особенностей работы scoped-стилей есть нюансы с использованием < !-- --> в шаблоне template.

Правильные способы:

Способ	Пример	Когда использовать
Стандартный CSS-комментарий (рекомендуется)	`/* Это комментарий */`	Всегда. Это единственный безопасный способ внутри < style scoped>.
Комментарий для конкретного браузера	`/! Важный комментарий /`	Если нужно сохранить комментарий в минифицированном CSS.

Пример в компоненте:

< template>
  < div class="my-component">Привет, мир!< /div>
< /template>

< style scoped>
/* Это главный комментарий для scoped-стилей.
   Он будет корректно обработан и удален при сборке. */
.my-component {
  color: blue; /* Можно комментировать и в конце строки */
  margin: 10px;
}

/*! Этот комментарий останется даже после минификации */
.another-class {
  font-weight: bold;
}
< /style>

Способ, который НЕ работает: HTML/XML-комментарий `< !-- -->` внутри < style> вызовет ошибку или будет проигнорирован.

< style scoped>
  < !-- ЭТО НЕ БУДЕТ РАБОТАТЬ! -->
  .my-class { color: red; }
< /style>

Почему это важно? Тег < style scoped> обрабатывается специальными инструментами (например, Vue Loader или Vite). Они:

1. Извлекают CSS-правила из тега.

2. Обрабатывают их с помощью PostCSS, добавляя уникальные атрибуты (`data-v-xxxxxx`) к селекторам, чтобы стили применялись только к текущему компоненту (это и есть "scoped").

3. Компилируют результат в стандартный CSS.

В этом процессе распознаются и корректно обрабатываются только CSS-синтаксис и CSS-комментарии.

Дополнительные возможности. Если вам нужно временно отключить большой блок стилей, можно обернуть его в специальный CSS-комментарий:

< style scoped>
/* Рабочие стили
.component { ... }
*/

/*
Отключенный блок стилей:
.old-component {
  color: red;
  margin: 0;
}
*/
< /style>

Для сложных проектов с препроцессорами (Sass/SCSS, Less) синтаксис комментариев сохраняется (для SCSS: `//` и `/* */`).

Вывод: всегда используйте `/* */` для комментариев внутри < style scoped>. Это гарантирует корректную работу инструментов сборки Vue и избегает ошибок.

[Ссылки]

1. Vue 3, быстрый старт.