SQL 쿼리 정렬과 주석 달기 실전 가이드 — 초보 개발자도 읽히는 쿼리 쓰는 법

SQL은 단순히 데이터를 가져오는 언어가 아니라,

협업과 유지보수를 위한 커뮤니케이션 도구입니다.

정리되지 않은 쿼리는 성능보다 앞서 가독성부터 무너집니다.

 

이번 글에서는 초보 개발자도 손쉽게 따라할 수 있는 SQL 줄 맞춤과 주석 정리의 실전 팁을

예시 중심으로 정리했습니다.

 

 

1. SQL 코드 가독성이 중요한 이유

SQL은 비즈니스 로직의 핵심입니다. 하지만 SELECT, JOIN, WHERE, GROUP BY 등이

뒤섞인 쿼리는 정렬 기준이 없으면 ‘한 줄 지옥’이 되기 쉽습니다. SQL 가독성을 높이면

디버깅, 리뷰, 성능 튜닝이 훨씬 빨라집니다.

 

또한 협업 시 “누가 쓴 쿼리인지”보다 “어떤 의도로 썼는지”가

명확하게 보이게 만드는 것이 중요합니다.

그 핵심이 바로 **일관된 포맷팅과 주석 습관**입니다.

 

2. SQL 줄맞춤 기본 원칙

SQL은 프로그래밍 언어처럼 블록 구조가 없기 때문에, 줄맞춤(Formatting)이

코드 구조를 대신합니다. 다음은 가장 기본적인 들여쓰기 규칙입니다.

SELECT 
    user_id, 
    user_name, 
    email
FROM 
    user_table
WHERE 
    status = 'ACTIVE'
ORDER BY 
    created_at DESC;

 

포인트는 키워드는 모두 대문자, 컬럼명과 테이블명은 한 줄씩 정렬하는 것입니다.

JOIN 문을 쓸 때도 같은 규칙을 적용합니다.

SELECT 
    u.user_name, 
    o.order_id, 
    o.amount
FROM 
    users u
INNER JOIN 
    orders o ON u.user_id = o.user_id
WHERE 
    o.amount > 10000;

 

이런 정렬 습관만으로도 “읽히는 SQL”이 됩니다.

 

 

3. 자동 포맷터 활용하기 (온라인 & IDE)

SQL 자동 정렬은 수동보다 훨씬 효율적입니다.

다음과 같은 무료 툴을 활용해보세요.

• SQLFormat.org — 간단한 웹 포맷터
• DBeaver — Ctrl + Shift + F 로 자동 정렬
• DataGrip — Ctrl + Alt + L 로 포맷팅
• VSCode — “SQL Formatter” 확장팩 사용

이 툴들은 쿼리를 자동으로 들여쓰기 정렬하며, 키워드 대문자화, 불필요한 공백 제거,

컬럼 정렬을 지원합니다.

팀 단위에서는 동일한 포맷 설정 파일을 공유하면 좋습니다.

 

4. SQL 주석(Comment) 작성법

주석은 쿼리의 ‘의도’를 명확히 표현하는 도구입니다.

SQL에서는 다음 두 가지 형식을 사용합니다.

• 라인 주석: -- 주석 내용
• 블록 주석: /* 여러 줄 주석 */

예시:

/* 최근 30일간 주문 금액이 높은 고객 조회 */
SELECT 
    customer_id, 
    SUM(order_amount) AS total_amount
FROM 
    orders
WHERE 
    order_date >= SYSDATE - 30
GROUP BY 
    customer_id
ORDER BY 
    total_amount DESC;

 

주석은 쿼리의 목적, 범위, 변경 이력 등을 간단히 남기는 용도로만 사용합니다.

너무 장황하게 설명하기보다 ‘한눈에 의도 파악’이 가능한 한두 줄이 이상적입니다.

 

5. 협업을 위한 SQL 정리 습관

팀 프로젝트에서는 포맷팅 규칙을 통일해두면 리뷰와 유지보수가 훨씬 간편해집니다.

다음 항목을 팀 규칙으로 지정해보세요.

1. 모든 키워드는 대문자, 컬럼명은 소문자
2. JOIN 문은 줄 단위 정렬, ON 조건은 들여쓰기
3. WHERE 절은 조건마다 줄 바꿈
4. ORDER BY, GROUP BY는 마지막에 별도 블록으로 표시
5. 주석은 SELECT문 위에 한 줄

 

마무리

SQL 쿼리를 정리하는 습관은 단순한 포맷팅이 아니라 사고의 구조화 훈련입니다.

들여쓰기, 공백, 주석 하나하나가 당신의 논리력을 반영합니다.

이제 Java, JSP, SQL 세 영역의 정리법을 익혔다면,

당신의 코드는 이미 ‘읽히는 코드’가 되어 있을 거예요.

 

3일 시리즈 완독을 축하드립니다 🎉

북마크해두고 꾸준히 성장하는 개발 습관을 이어가세요.