주석(Comment)의 역할과 코딩할 때 꼭 써야 하는 이유

코딩할 때 주석이 왜 그렇게 중요할까

프로그래밍을 처음 배울 때 우리는 보통 화면에 글자를 출력하는 법이나 계산을 하는 법부터 시작합니다. 그러다 코드가 점점 길어지고 복잡해지면서 벽에 부딪히게 됩니다.

내가 직접 짰던 코드인데도 일주일만 지나면 무슨 뜻으로 작성했는지 기억나지 않는 순간이 찾아옵니다. 이럴 때 도움이 되는 것이 주석입니다.

주석은 컴퓨터가 실행하지 않고, 사람이 읽기 위해 코드 옆에 남겨 두는 메모입니다. 이 코드가 무엇을 하는지, 왜 그렇게 작성했는지를 적어 둘 수 있습니다.

집을 지을 때 설계도에 적어 두는 메모처럼, 주석은 코드가 어떤 목적으로 만들어졌는지 알려 주는 표시 역할을 합니다.

좋은 주석이 가지는 실질적인 가치

개발 현장에서 주석은 단순한 낙서가 아니라, 코드를 고치거나 여럿이 함께 작업할 때 서로의 의도를 전하는 수단입니다. 주석이 주는 실용적인 이점은 다음과 같습니다.

• 작성자의 의도를 명확하게 전달해 협업 효율을 높여 줍니다
• 복잡한 로직이나 알고리즘을 빠르게 이해할 수 있도록 돕습니다
• 시간이 지난 후 코드를 다시 볼 때 기억을 되살리는 시간을 단축해 줍니다
• 미완성된 부분이나 수정해야 할 사항을 표시하여 실수를 방지합니다

프로그래밍 언어별 주석 쓰는 방법

주석을 표시하는 기호는 프로그래밍 언어마다 다릅니다. 이 블로그에서 다룬 파이썬, 자바스크립트, HTML에서 주석을 쓰는 방법은 다음과 같습니다.

파이썬은 # 기호로 주석을 시작합니다. # 뒤에 쓴 글은 컴퓨터가 실행하지 않습니다.

# 인사말을 화면에 출력한다
print("안녕하세요")  # 줄 끝에도 주석을 쓸 수 있다

자바스크립트는 // 기호로 한 줄 주석을 쓰고, 여러 줄 주석은 /* 와 */ 사이에 씁니다.

// 인사말을 화면에 출력한다
console.log("안녕하세요"); // 줄 끝에도 주석을 쓸 수 있다

/* 여러 줄 주석은
   이렇게 씁니다 */

HTML 주석은 아래 코드처럼 씁니다. 브라우저 화면에는 주석 안의 글이 나타나지 않습니다.

<!-- 이 부분은 주석이라 화면에 보이지 않습니다 -->
<p>이 글은 화면에 보입니다.</p>

VS Code에서는 주석으로 바꿀 줄을 클릭하고 Command + /를 누르면 됩니다. 파이썬 파일에서는 그 줄 앞에 #이 붙어 주석이 되고, 다른 언어에서는 그 언어에 맞는 주석 기호가 붙습니다. 윈도우에서는 Ctrl + /를 누릅니다. 아래 사진은 세 번째 줄을 이 단축키로 주석 처리한 모습입니다.

상황에 따라 다르게 쓰이는 주석의 종류

주석은 작성하는 목적과 위치에 따라 여러 가지 형태로 나뉩니다. 각 유형별 특성을 잘 이해하고 활용하면 코드의 가독성을 한층 더 높일 수 있습니다.

설명형 주석

복잡한 계산식처럼 읽기 어려운 부분에, 왜 이런 방식을 선택했는지 그 이유를 적어 두는 주석입니다. 코드만으로는 드러나지 않는 배경을 보완해 줍니다.

TODO 주석

지금 당장 구현하지 못했거나 나중에 추가해야 할 기능, 혹은 임시로 작성해 둔 코드 위에 남기는 메모입니다. 개발 과정에서 해야 할 일을 놓치지 않도록 돕는 스티커 메모와 같습니다.

문서화 주석

함수나 클래스가 어떤 일을 하고, 어떤 값을 받아서 무엇을 돌려주는지 정해진 형식으로 적어 두는 주석입니다. 다른 개발자가 그 기능을 가져다 쓸 때 코드 내부를 열어 보지 않고도 사용법을 알 수 있게 해 줍니다.

주석에 대한 흔한 오해와 진실

주석에 대해서는 흔히 알려진 오해가 몇 가지 있습니다. 이런 오해 때문에 주석을 아예 쓰지 않거나, 반대로 지나치게 많이 쓰는 경우가 생기기도 합니다.

가장 흔한 오해 중 하나는 코드가 완벽하다면 주석이 전혀 필요 없다는 생각입니다. 물론 변수 이름이나 함수 이름을 직관적으로 잘 짓는 것은 매우 중요합니다. 하지만 코드만으로는 ‘왜’ 이 방식을 택했는지 그 맥락을 온전히 설명하기 어렵습니다. 코드는 ‘무엇’을 하는지 보여 주지만, 주석은 ‘왜’ 그렇게 했는지를 말해 줍니다.

또 다른 오해는 주석을 많이 적을수록 좋은 코드라는 생각입니다. 이미 코드만 봐도 뻔한 내용을 장황하게 설명하는 주석은 오히려 읽는 데 방해가 됩니다. 예를 들어 숫자에 1을 더하는 코드 옆에 ‘1을 더한다’고 길게 적어 두는 것은 코드를 읽기 불편하게 만들 뿐입니다. 주석은 꼭 필요한 곳에 간결하게 작성해야 가치가 살아납니다.

실용적인 주석 작성을 위한 유용한 팁

효과적인 주석을 작성하기 위해 기억해 두면 좋은 원칙이 몇 가지 있습니다.

1. 코드가 바뀌면 주석도 함께 고쳐야 합니다. 코드는 바뀌었는데 옛날 설명이 그대로 남아 있으면 읽는 사람이 오해할 수 있습니다.
2. 감정적인 표현이나 코드와 관계없는 이야기는 빼고, 사실과 의도 위주로 간결하게 작성합니다.
3. 코드 한 줄마다 주석을 달기보다, 한 덩어리의 코드가 하는 일을 설명하는 데 집중합니다.
4. 한국어나 영어 등 팀원들이 가장 편하게 이해할 수 있는 언어로 일관성 있게 작성합니다.

주석을 습관으로 만드는 방법

주석은 코드를 쓴 사람의 생각을 남기는 기록입니다. 나중에 그 코드를 다시 보게 될 나 자신이나 함께 일하는 사람에게 도움이 됩니다.

주석은 나중에 몰아서 쓰기보다 코드를 짜는 순간에 함께 남기는 편이 좋습니다. 기억이 또렷할 때 적어 둔 짧은 메모 한 줄이, 나중에 코드를 다시 읽는 시간을 줄여 줍니다.

주석을 쓰다 보면 내 코드를 처음 보는 사람의 입장에서 다시 읽어 보게 됩니다. 그 과정에서 이름이 헷갈리는 변수나 지나치게 복잡한 부분을 발견해 고치기도 합니다.

자주 묻는 질문과 답변

주석은 영어로 써야 할까요, 한국어로 써야 할까요?

혼자 만드는 개인 프로젝트라면 편한 언어로 써도 됩니다. 여러 나라 사람이 함께 작업하는 프로젝트나 오픈소스에서는 영어로 쓰는 경우가 많습니다. 팀에서 일한다면 팀이 정한 규칙을 따르는 것이 좋습니다.

주석 처리한 코드는 그대로 남겨 둬도 되나요?

나중에 쓸지도 몰라서 주석 처리한 코드를 오래 남겨 두는 경우가 많습니다. 하지만 깃(Git) 같은 버전 관리 도구를 쓰고 있다면, 필요 없어진 코드를 지워도 이전 기록에서 다시 찾을 수 있습니다. 남겨 둔 코드가 많아지면 읽기 어려워지니 정리하는 것이 좋습니다.

자동 문서화 도구를 사용하면 주석을 안 써도 되나요?

문서화 도구는 코드에 적어 둔 설명을 모아서 문서로 만들어 주는 경우가 많습니다. 그래서 도구를 쓰더라도 설명은 사람이 직접 적어야 합니다. 도구는 틀을 만들어 줄 뿐, 코드의 의도와 배경은 주석에 담겨야 합니다.