Комментарии в Bash — практический разбор

Зачем нужны комментарии в Bash

В Bash-скриптах комментарии особенно важны, потому что shell-код часто лаконичный и неочевидный. Хороший комментарий объясняет почему сделано именно так, а не просто дублирует команду.

Синтаксис комментария

Однострочный комментарий начинается с #:

# Это комментарий
echo "Hello"

Всё после # до конца строки игнорируется интерпретатором.

Inline-комментарии

Можно писать комментарий в конце строки:

cp "$src" "$dst"  # Копируем подготовленный конфиг

Используй это умеренно, чтобы строка не становилась нечитаемой.

Важное исключение: shebang

Первая строка:

#!/usr/bin/env bash

технически тоже начинается с #, но это не комментарий, а директива запуска (shebang).

“Многострочные” комментарии

В Bash нет отдельного синтаксиса block-comments как в C/JS. Обычно используют набор однострочных:

# Шаг 1: проверяем зависимости
# Шаг 2: готовим временную директорию
# Шаг 3: запускаем обработку

Иногда встречают workaround через here-doc, но для обычных скриптов лучше не усложнять.

Что комментировать

Комментируй:

• неочевидные ограничения среды;
• причины нестандартного решения;
• потенциально опасные операции (rm, chmod -R, миграции);
• бизнес-правила, которые не видны из кода.

Не комментируй:

• очевидные действия (i=i+1, echo, cd без контекста);
• то, что и так понятно из хороших имён функций/переменных.

Пример хороших комментариев

#!/usr/bin/env bash
set -euo pipefail

# Используем lock-файл, чтобы избежать параллельного запуска по cron.
LOCK_FILE="/tmp/report.lock"

# shellcheck disable=SC trap нужен для гарантированного удаления lock-файла при любом выходе.
trap 'rm -f "$LOCK_FILE"' EXIT

Частые ошибки

1. Комментарий устарел и противоречит коду.
2. Слишком много комментариев-шумов вместо понятных имён.
3. Комментарии не объясняют мотивацию решения.

Практический стиль

• Пиши коротко и по делу.
• Предпочитай формулировки вида: «почему/зачем», а не «что».
• При правке логики проверяй и актуальность комментариев.

Вывод

Комментарии в Bash — это инструмент поддержки, а не украшение. Лучший эффект дают короткие, точные пояснения к неочевидным местам и рискованным операциям.