주석 잘 다는 법: 초보 개발자를 위한 실전 코드 주석 가이드

프로그래밍을 막 시작했을 때, 정말 많은 이야기를 들었어요. 그중엔 진짜 도움 되는 것도 있었고, 듣고 나면 더 혼란스러운 것도 있었죠. "좋은 코드는 주석이 필요 없다"는 말도 그 중 하나였어요. 처음엔 그 말이 맞는 줄 알고, 괜히 주석 달면서 찜찜한 기분이 들었죠. 마치 내가 뭔가 부족해서 보완하려는 것처럼 느껴지기도 했고요. 근데 지금은 확신해요. 주석을 다는 건 약점이 아니라, 함께 일하는 사람을 생각하는 따뜻한 행동이에요.

 

주석, 왜 써야 할까? 결국 코드는 '사람'을 위한 것

 

주석, 왜 써야 할까? 결국 코드는 '사람'을 위한 것

• 코드는 단순히 기계가 이해하는 게 아니라, 사람 간의 소통 도구예요.
• 잘 쓴 주석은 코드의 목적과 맥락을 빠르게 전달해줘요.
• 주석은 단순 설명이 아니라, ‘왜’ 이 코드가 필요한지를 알려주는 힌트가 될 수 있어요.

코드는 컴퓨터만 보라고 쓰는 게 아니잖아요. 같이 일하는 동료, 며칠 뒤의 나, 그리고 프로젝트를 맡게 될 다음 사람 모두가 코드를 보게 되죠. 아무리 코드가 정갈해도, 주석 하나로 이해의 문이 활짝 열릴 수 있어요.

물론 대충 써놓은 주석은 오히려 혼란을 주기도 해요. 근데 잘 쓴 주석은 진짜 보석 같아요. 단순한 설명이 아니라, '왜' 이렇게 했는지를 알려주는 힌트가 되거든요.

 

 

"좋은 코드는 설명이 필요 없다"? 현실은 달라요

• 주석을 다는 게 잘못처럼 느껴질 수 있지만, 오히려 이해를 돕는 도구예요.
• 맥락과 목적은 코드만으로는 설명되지 않는 경우가 많아요.
• 주석은 미래의 나나 동료가 코드를 쉽게 이해하게 도와줘요.

이 말, 정말 자주 들었어요. 마치 주석을 쓰면 내가 코드를 잘 못 짰다는 뜻처럼 느껴졌죠. 그래서 처음엔 괜히 눈치 보면서 조심조심 주석을 달았던 기억이 나요. 근데 어느 순간 깨달았죠. 아무리 코드가 예뻐도, 맥락은 코드만으론 설명되지 않더라고요.

처음엔 어색했지만, 지금은 당당하게 씁니다. 주석 덕분에 과거의 나도, 동료도 코드를 훨씬 쉽게 이해할 수 있었으니까요. 주석, 생각보다 진짜 큰 차이를 만들어요.

 

그럼 어떤 주석이 좋은 걸까?

 

그럼 어떤 주석이 좋은 걸까?

• 모든 주석이 도움이 되는 건 아니에요. 잘 쓴 주석은 명확한 정보를 줘요.
• 요약 주석은 흐름을 잡아주고, 설명 주석은 종종 불필요한 반복이 될 수 있어요.
• 주석을 쓸 땐 정보 전달과 맥락 설명에 집중하는 게 중요해요.

주석도 다 같은 주석이 아니에요. 어떤 건 정말 도움이 되지만, 어떤 건 안 하느니만 못할 때도 있죠.

 

 

1. 요약 주석: 복잡한 코드에 방향을 잡아주는 안내판

요약 주석은 말 그대로 ‘요약’입니다. 몇 줄씩 이어지는 코드가 어떤 걸 하려는지 한두 줄로 정리해줘요. 마치 길 찾을 때 ‘여기서 좌회전’ 해주는 이정표 같은 거죠.

예시 (페이스북 로그인 처리):

# 페이스북 연결 오류 처리

이 한 줄만 봐도, 아 이 코드가 뭐 하려는구나~ 하고 감이 와요. 코드 흐름 파악할 때 진짜 큰 도움이 돼요. 특히 컨트롤러처럼 구조가 복잡한 곳에서는 필수죠.

 

요약 주석의 장점:

• 처음 보는 사람도 금방 흐름을 파악할 수 있어요
• 코드 살짝 바뀌어도 주석은 그대로 쓸 수 있어요
• 협업할 때 설명할 필요가 확 줄어요

 

2. 설명 주석: 그냥 코드 읽어주는 주석은 이제 그만

반대로, 설명 주석은 좀 불필요한 경우가 많아요. 코드를 그대로 주석으로 옮겨놨을 뿐이라서요.

 

이런 건 별로:

# 상태 코드가 200이 아닌지 확인
if request.status_code != 200:

이런 주석은 그냥 눈에 거슬려요. 코드가 이미 다 말해주고 있잖아요. 굳이 다시 쓰지 않아도 돼요.

 

설명 주석이 아쉬운 이유:

• 공간만 차지하고 정보는 없어요
• 굳이 안 써도 되는 이야기만 늘어놔요
• 코드 바뀌면 주석도 같이 틀릴 위험이 있어요

이런 주석 때문에 "주석 필요 없다"는 얘기가 나오는 거예요. 이해는 되지만, 그래서 ‘좋은 주석’이 더 중요해요.

 

문서형 주석: 파일과 함수의 소개글 같은 느낌

• 문서형 주석은 코드 덩어리의 목적과 사용 조건 등을 정리해줘요.
• 보기 좋은 장식보다는 유지보수가 쉬운 형식이 더 좋아요.
• 간단하지만 핵심을 담은 문서형 주석이 가장 효율적이에요.

문서형 주석은 파일이나 함수, 클래스 맨 위에 쓰는 주석이에요. 그 코드가 무슨 일을 하는지, 특별한 조건이 있는지 등을 간단히 알려주는 거죠.

 

문서형 주석에 이런 내용이 있으면 좋아요:

• 이 코드 덩어리가 하는 일 한 줄 설명
• 알아둬야 할 조건이나 사전 정보
• 작성자, 날짜 같은 참고 정보

 

피해야 할 스타일:

• 예쁘게 보이려고 줄 맞추는 장식들

왜냐고요? 단어 하나만 추가해도 정렬 다 틀어져서 다시 맞춰야 해요. 그거 진짜 귀찮습니다.

 

예쁜데 귀찮은 예:

/**********************************************
 *     페이스북 컨트롤러입니다               *
 *     로그인 처리 및 에러 리다이렉트 담당     *
 **********************************************/

보기엔 괜찮은데, 수정하려면 골치 아파요.

 

현실적으로 좋은 예:

"""
FacebookController: 페이스북 로그인을 처리하고, 오류가 생기면 리다이렉트합니다.
"""

깔끔하고, 바꾸기도 쉽고, 정보도 잘 전달돼요.

 

한마디로 말하자면: 주석은 결국 사람을 위한 것

 

한마디로 말하자면: 주석은 결국 사람을 위한 것

• 주석은 동료와 미래의 나를 위한 작은 배려예요.
• “좋은 코드는 설명이 필요 없다”는 말에 휘둘릴 필요 없어요.
• 진심을 담은 주석은 누군가에게 큰 도움이 될 수 있어요.

 

주석은 내 코드를 보는 사람에 대한 작은 배려입니다. 잘 쓰면, 누군가의 시간을 아껴주고, 실수를 줄여주고, 이해를 도와줄 수 있어요.

괜히 "좋은 코드는 설명이 필요 없다"는 말에 얽매이지 마세요. 그 말은 좋지 않은 주석을 피하라는 뜻일 뿐, ‘모든 주석이 나쁘다’는 말은 아니거든요.

주석을 쓸 땐, 친절한 친구에게 설명한다는 느낌으로 써보세요. 어렵지 않아요. 진심만 담겨 있다면, 그건 이미 좋은 주석이에요.

 

기억해두면 좋은 팁

• 좋은 주석은 왜 그 코드를 썼는지를 알려줍니다.
• 문서형 주석은 큰 그림을 보여줘요.
• 중복 설명은 지양하고, 핵심만 콕콕.
• 심플한 주석이 유지보수도 쉬워요.
• 코드는 말이고, 주석은 그 말의 따뜻한 속뜻이에요.

 

마무리하며

• 주석은 단순한 습관이 아니라, 더 나은 협업을 위한 노력이에요.
• 완벽하지 않아도 괜찮아요. 중요한 건 상대방을 생각하는 마음이에요.
• 당신의 작은 주석이 누군가에게 큰 도움이 될 수 있어요.

 

주석은 그냥 습관이 아니라, 함께 일하는 사람을 위한 작은 배려입니다. 나중의 나, 동료들, 그리고 처음 이 코드를 보는 누군가를 위해 쓰는 거예요.

그러니까 너무 겁내지 말고, 하고 싶은 말을 주석으로 남겨보세요. 틀려도 괜찮아요. 나중에 수정하면 되니까요. 중요한 건, ‘이해를 도우려는 마음’이에요.

아마 미래의 당신이, 그리고 당신 옆에서 일하는 누군가가, 그 주석 하나 덕분에 미소 지을지도 몰라요.