주석에는 두 가지 스타일이 있다
자바스크립트 주석은 크게 두 가지 문법으로 나뉜다. 먼저 한 줄 주석은 //로 시작해서 해당 줄 끝까지 이어진다:
여러 줄 주석은 /*로 시작해서 */를 만나는 순간 끝납니다. 원하는 만큼 여러 줄에 걸쳐 쓸 수 있죠:
두 형식 모두 자바스크립트 엔진은 전혀 신경 쓰지 않고 그냥 지나칩니다. 주석은 오로지 사람을 위한 것이죠. 지금의 나, 동료, 그리고 6개월 뒤에 이 코드를 다시 열어볼 미래의 나를 위한 장치입니다.
한 줄 주석 (//)
실무에서 가장 자주 쓰게 되는 건 // 형태입니다. // 뒤에 오는 같은 줄의 내용은 전부 주석으로 처리되고, 줄이 바뀌면 다시 평범한 코드로 돌아옵니다:
끝에 붙이는 주석(문장 뒤쪽에 다는 주석)은 짧은 메모 정도라면 괜찮습니다. 다만 줄바꿈이 일어날 만큼 길어진다면, 코드 위쪽에 별도의 줄로 빼세요. 줄 끝에 길게 달린 주석은 에디터에서 잘리기 일쑤고, 읽는 사람도 그냥 지나치게 됩니다.
여러 줄 주석 (블록 주석)
/* */를 꺼낼 만한 상황은 크게 두 가지입니다. 한 줄을 넘어가는 주석을 달아야 할 때, 그리고 식(expression) 한가운데에 주석을 끼워 넣어야 할 때죠.
한 가지 주의할 점은 블록 주석은 중첩이 안 된다는 겁니다. 바깥쪽 주석 안에 있다고 생각해도, 처음 만나는 */에서 주석이 바로 끝나버리거든요:
/* 바깥 /* 안쪽 */ 아직 바깥 */
// SyntaxError — 처음 만난 */ 가 블록을 닫아버리기 때문에
// "아직 바깥 */" 는 유효하지 않은 코드가 됩니다.
/* */가 이미 들어 있는 코드를 주석 처리해야 한다면, 줄마다 //를 붙이는 방식으로 해결하세요.
코드 주석 처리하기
디버깅을 하다 보면 몇 줄을 잠깐 꺼두고 싶을 때가 많습니다. 이럴 때는 두 가지 주석 방식 모두 쓸 수 있어요:
어떤 에디터든 주석 처리 단축키가 있다. 윈도우·리눅스는 Ctrl+/, 맥은 Cmd+/를 누르면 선택한 줄에 //이 토글된다. 한 번만 익혀두면 매일같이 쓰게 된다.
주석 처리한 코드는 어디까지나 임시여야 한다. // 예전 버전, 혹시 몰라서 남겨둠 같은 문구와 함께 죽은 코드 무덤을 커밋하지 말자. 예전 코드는 Git이 알아서 기억해 준다. 그냥 지우면 된다.
무엇(What)이 아니라 왜(Why)를 적어라
쓸모 있는 주석과 소음을 가르는 단 하나의 기준이다. 무엇을 하는지는 코드만 봐도 알 수 있다. 좋은 주석은 왜 그렇게 했는지를 알려준다.
이런 건 소음이다:
코드를 읽으면 이미 알 수 있는 내용을 굳이 주석으로 적어둔 셈이죠. 아래 예시와 비교해 보세요.
두 주석 모두 코드만 봐서는 알 수 없는 정보 — 외부 제약이나 문서화된 특이사항 — 을 짚어주고 있습니다. 좋은 주석의 기준이 바로 이겁니다. 주석을 지웠을 때 아무도 헷갈리지 않는다면, 그 주석은 제 역할을 못 하고 있던 거예요.
JSDoc: 도구가 읽어주는 주석
JSDoc은 함수를 정형화된 방식으로 설명하는 블록 주석 컨벤션입니다. 에디터나 타입 체커가 이 주석을 읽어서 더 똑똑한 자동완성과 호버 문서를 보여줍니다:
/** (별 두 개)로 시작해야 일반 블록 주석이 아닌 JSDoc으로 인식됩니다. 모든 함수에 JSDoc을 달 필요는 없고, 공개 API나 공용 유틸리티처럼 여러 곳에서 쓰이는 코드, 또는 코드만 봐서는 타입이 잘 드러나지 않는 곳에 붙여주면 가장 효과적입니다.
알아두면 좋은 주석 습관들
- 주석은 설명하려는 코드 바로 옆에 두세요. 관련 코드에서 열 줄쯤 떨어진 주석은 시간이 지나면서 실제 동작과 어긋나기 쉽습니다.
- 코드를 수정했다면 주석도 함께 고치세요. 오래된 주석은 아예 없느니만 못합니다. 다음에 코드를 읽는 사람에게 거짓말을 하게 되니까요.
- 주석을 더 달기보다는 이름을 잘 짓는 게 먼저입니다.
const d = 86400000;에는 주석이 필요하지만,const MILLISECONDS_PER_DAY = 86_400_000;에는 필요 없죠. - 임시로 남겨둔 문제는
TODO:나FIXME:로 표시하세요. 대부분의 에디터가 이 키워드를 강조해주고, 나중에 검색으로 찾기도 쉽습니다.
HTML 주석과 자바스크립트 주석은 다릅니다
HTML 파일 안에 자바스크립트를 작성할 때는 두 주석 방식을 헷갈리지 않도록 주의하세요. HTML에서는 <!-- -->를 쓰지만, 자바스크립트에서는 //와 /* */를 씁니다. <script> 태그 안에서는 자바스크립트 방식만 제대로 동작합니다:
<script>
// 올바름 — <script> 내부의 JS 주석
/* 이것도 올바름 */
<!-- 잘못됨 — 이것은 HTML 주석이며 JS를 깨뜨립니다 -->
console.log("안녕");
</script>
브라우저가 예전에는 오래된 브라우저 호환성 때문에 스크립트 안의 <!-- -->를 용인해 주긴 했지만, 지금은 쓸 수 없는 문법이라고 생각하고 넘어가세요.
다음 주제: 변수 선언하기
이제 코드에 주석을 달 수 있게 됐으니 본격적으로 코드를 써볼 차례입니다. 자바스크립트에서 변수를 선언하는 방법은 let, const, var 이렇게 세 가지인데요, 이 중 어떤 걸 쓸지 고르는 게 매 줄마다 마주하는 첫 번째 진짜 고민입니다. 바로 이어서 살펴보겠습니다.
자주 묻는 질문
자바스크립트에서 주석은 어떻게 작성하나요?
한 줄 주석은 //를 씁니다. // 뒤에 쓴 내용은 그 줄 끝까지 무시돼요. 여러 줄을 한 번에 처리하고 싶다면 /* ... */로 감싸면 됩니다. .js 파일 어디서든, HTML의 <script> 태그 안에서도 똑같이 동작합니다.
//와 /* */의 차이는 뭔가요?
//와 /* */의 차이는 뭔가요?//는 현재 줄 끝까지만 주석 처리하고 끝납니다. 반면 /* */는 /*에서 시작해 다음 */를 만날 때까지 이어지기 때문에 여러 줄을 감싸거나, 식 중간에 끼워 넣는 인라인 주석으로도 쓸 수 있어요. 짧은 메모는 //, 여러 줄이 필요하거나 표현식 일부에 설명을 붙이고 싶을 땐 /* */가 편합니다.
코드 블록을 통째로 주석 처리하려면 어떻게 하나요?
/* */로 감싸거나, 줄마다 //를 붙이면 됩니다. 대부분의 에디터에는 단축키가 있어요 — VS Code 기준 Ctrl+/ (맥은 Cmd+/)를 누르면 선택한 줄에 //가 자동으로 붙었다 떨어졌다 합니다. 단, /* */ 안에 또 /* */를 넣는 중첩은 금지입니다. 안쪽 */가 바깥 주석을 먼저 닫아버려서 구문 오류가 나요.
주석은 언제 쓰는 게 좋을까요?
**'무엇'이 아니라 '왜'**를 적으세요. 특이한 우회 처리, 도메인 규칙, 성능 최적화처럼 코드만 봐서는 의도가 안 드러나는 부분에 이유를 남기는 게 핵심입니다. 코드가 이미 말해주는 내용을 또 설명하는 주석은 오히려 노이즈예요. 변수명과 함수명을 잘 지어두면 주석 자체가 필요 없어지는 경우가 많습니다.
