Комментарии и форматирование запросов
Комментарии и форматирование запросов
На протяжении этого модуля вы писали всё более сложные SQL-запросы: сначала SELECT *, затем конкретные колонки, псевдонимы, DISTINCT, вычисляемые выражения. Сложность будет расти — и вместе с ней растёт важность читаемости кода. В этом уроке разберём, как писать SQL, который легко понять и сопровождать: комментарии, форматирование, соглашения об именах.
Два вида комментариев
В SQL есть два вида комментариев. Оба полностью игнорируются СУБД при выполнении запроса.
Однострочный комментарий — два дефиса --. Всё от -- до конца строки является комментарием:
-- Получаем список активных сотрудников
SELECT name, department -- только нужные колонки
FROM employees;
-- TODO: добавить фильтр по отделу
Многострочный (блочный) комментарий — /* ... */. Может занимать несколько строк или встраиваться внутри строки:
/*
Отчёт по продажам за текущий месяц.
Автор: Иван Иванов
Дата: 2024-03-15
*/
SELECT product_name,
quantity * unit_price AS total /* итог по позиции */
FROM order_items;
Блочные комментарии редко встречаются в повседневных запросах, но полезны для заголовков скриптов и документирования сложной логики.
Когда писать комментарии
Хороший комментарий объясняет зачем, а не что. Код сам говорит «что» — имена колонок, операции. Комментарий нужен, когда логика неочевидна:
-- Умножаем на 1.2 — НДС 20%, который не включён в прайс
SELECT price * 1.2 AS price_with_vat
FROM products;
Без этого комментария следующий разработчик (или вы сами через месяц) будет гадать: «почему 1.2, откуда это число?».
Плохой комментарий — когда он повторяет код без добавленной ценности:
-- Выбираем имя и цену
SELECT name, price
FROM products;
Здесь комментарий ничего не добавляет — запрос и так читается как «выбрать имя и цену». Такой комментарий лучше удалить.
Хорошее правило: если запрос очевиден, комментарий не нужен. Если нужно объяснить бизнес-логику или нестандартное решение — пишите.
Форматирование: зачем оно важно
SQL игнорирует лишние пробелы и переносы строк. Эти два запроса выполнятся идентично:
select name,price,stock from products where stock>0 order by price;
SELECT name,
price,
stock
FROM products
WHERE stock > 0
ORDER BY price;
Результат одинаковый. Но второй запрос читается в разы легче. На практике SQL-запросы бывают длиной 50–100 строк — без форматирования это превращается в нечитаемую кашу.
Базовые правила форматирования
Единого стандарта форматирования SQL нет — разные команды используют разные стили. Но есть базовые принципы, которых придерживается большинство:
Ключевые слова — заглавными буквами:
SELECT name FROM employees WHERE department = 'HR';
Это визуально отделяет «язык» от «данных».
Каждая клауза — с новой строки:
SELECT name,
salary
FROM employees
WHERE department = 'HR'
ORDER BY name;
Когда клауз много, такой стиль моментально показывает структуру запроса.
Выравнивание по правому краю ключевых слов:
SELECT name,
salary
FROM employees
WHERE department = 'HR'
ORDER BY name;
Этот стиль — «river style» — удобен тем, что все части запроса выровнены по вертикали. Но он опциональный; даже без такого выравнивания структура читается.
Колонки в списке SELECT — каждая на новой строке с отступом:
SELECT id,
first_name,
last_name,
email,
created_at
FROM users;
Такой формат легко дополнять и редактировать: добавить новую колонку или закомментировать одну из существующих — одна строка, никакой путаницы.
Отступы и пробелы
SQL-сообщество не пришло к единому мнению об отступах — два пробела, четыре, или табуляция. Главное — быть последовательным внутри проекта. Если в команде есть соглашение — следуйте ему.
Пробелы вокруг операторов (=, >, +) — хорошая практика:
-- Читабельно
WHERE price > 1000 AND stock >= 5
-- Менее читабельно
WHERE price>1000 AND stock>=5
Оба варианта работают, но первый — стандарт в большинстве команд.
Имена в нижнем регистре через underscore
PostgreSQL хранит имена в нижнем регистре (если не использовать кавычки). Принятое соглашение — имена таблиц и колонок в snake_case:
-- Хорошо: snake_case
SELECT first_name, last_name FROM employee_data;
-- Плохо: camelCase (работает, но неудобно в SQL)
SELECT firstName, lastName FROM employeeData;
camelCase в именах баз данных вызывает проблемы: PostgreSQL приведёт firstName к firstname, и придётся писать "firstName" в кавычках каждый раз. snake_case этой проблемы лишён.
Форматирование вычисляемых выражений
Сложные вычисления в SELECT стоит разбивать на строки и выравнивать:
SELECT order_id,
quantity * unit_price AS subtotal,
quantity * unit_price * 0.13 AS tax,
quantity * unit_price * 1.13 AS total_with_tax
FROM order_items;
Когда все AS выровнены в столбик, легко видеть структуру вычислений. Это необязательно, но при нескольких вычисляемых колонках сильно помогает.
Комментирование частей запроса при отладке
Один из самых полезных приёмов при отладке — временно закомментировать часть запроса:
SELECT name,
price,
-- price * 0.2 AS discount, -- временно отключено
stock
FROM products;
Это быстрее, чем удалять и затем снова набирать строку. В psql сложно редактировать многострочный запрос, поэтому часто удобнее писать запросы в текстовом редакторе и копировать в консоль.
Инструменты форматирования
Для тех, кто работает с SQL профессионально, существуют автоматические форматтеры:
- pgFormatter — для PostgreSQL, доступен как онлайн-инструмент и командная строка
- SQL Formatter — популярная JavaScript-библиотека с онлайн-версией
- Встроенное форматирование в DBeaver, DataGrip и других GUI-клиентах
В начале обучения форматируйте вручную — это развивает понимание структуры запроса. Когда синтаксис станет привычным, автоматические инструменты ускорят работу.
Проверь себя: почему комментарий -- Выбираем name и price перед SELECT name, price FROM products — бесполезный?
Большой пример: хорошо vs плохо
Один и тот же запрос в двух вариантах. Плохой вариант:
select id,first_name||' '||last_name as name,salary,salary*12 as annual,department from employees where department='IT' order by salary desc;
Хороший вариант:
-- Сотрудники IT-отдела с годовой зарплатой, по убыванию дохода
SELECT id,
first_name || ' ' || last_name AS name,
salary AS monthly_salary,
salary * 12 AS annual_salary,
department
FROM employees
WHERE department = 'IT'
ORDER BY salary DESC;
Оба запроса делают одно и то же. Но второй:
- имеет комментарий с объяснением бизнес-смысла
- разбит на строки — легко добавить/убрать колонку
- использует выравнивание
AS— видно, что это вычисляемые значения - имеет пробелы вокруг операторов — не надо «читать по буквам»
Когда вы работаете в команде или возвращаетесь к своему коду через месяц, такой стиль экономит реальное время.
Форматирование в разных инструментах
В разных средах написание SQL выглядит по-разному:
psql — только терминал. Удобен для быстрых запросов, но редактировать длинный запрос неудобно. Совет: пишите длинные запросы в текстовом файле, копируйте в psql. Или используйте \e — это откроет редактор (vi или nano).
DBeaver, DataGrip, TablePlus — графические клиенты с подсветкой синтаксиса, автодополнением и встроенным форматтером. В реальной работе большинство специалистов используют именно такие инструменты.
Jupyter Notebook с расширением %%sql или библиотекой sqlalchemy — популярен среди аналитиков данных.
Код приложения (Python, Node.js, Java) — SQL часто пишется как строка внутри кода. Здесь форматирование особенно важно, потому что запрос теряется среди программного кода.
Практика: приведите в порядок свои запросы
По мере изучения курса старайтесь сразу писать запросы в хорошем стиле:
- Ключевые слова заглавными
- Каждая клауза с новой строки
- Комментарий, если логика неочевидна
- Имена в
snake_case
Это займёт чуть больше времени сейчас, но многократно окупится, когда запросы станут длиннее.
Краткий итог
--— однострочный комментарий;/* */— блочный; оба игнорируются СУБД- Хороший комментарий объясняет зачем, не что
- SQL нечувствителен к пробелам и переносам — форматирование только для людей
- Стандартные соглашения: ключевые слова ЗАГЛАВНЫМИ, клаузы с новой строки, имена таблиц и колонок в
snake_case - При отладке можно временно комментировать части запроса
- Последовательность важнее конкретного стиля — главное, чтобы команда использовала один подход
Что дальше
Вы завершили модуль про базовый SELECT. Вы умеете выбирать колонки, давать им псевдонимы, убирать дубликаты, вычислять выражения и форматировать запросы. Следующий модуль — фильтрация и сортировка. Это WHERE и ORDER BY — инструменты, которые превратят «верни всё» в «верни именно то, что нужно».