AI가 만들어내는 주석 믿고 써도될까?

"AI가 만들어내는 주석 믿고 써도될까?" - Nano Banana로 생성

 

 저희가 코드에 주석을 다는 이유가 뭘까요? 그 이유는 "코드만으로는 전달이 어려운 맥락"을 남겨서 미래의 나와 동료가 더 빠르고 안전하게 이해하고 변경하게 만들기 위해서입니다. 다만 주석은 잘 쓰면 자산, 못 쓰면 부채라서 "무엇을 언제 주석으로 남길지"가 핵심입니다.

 

최근에는 AI가 만들어내는 주석들에 대해 호기심을 갖고 믿고 이를 그대로 사용해도 될지에 대한 의문점들을 가져보았는데 이번 포스팅에서는 이에 대해 고찰해 본 경험에 대해 작성해 보도록 하겠습니다.

 

---

 

🤔 AI가 코드에 주석을 다는 이유는?

Clean Code - 로버트 C마틴

 

클린코드(Clean Code)의 저자 로버트 C마틴은 주석이 사실상 필요악이다라고 주장했습니다. 주석을 사용하는 것은 대부분 실패한 경우이기 때문에 가능한 안 쓰는 게 좋고 관리포인트가 늘어서 유지보수가 어려워진다는 점을 단점으로 내세웁니다.

 

그럼에도 대다수의 AI들이 주석을 활용하는 이유가 무엇일까요? AI가 코드를 만들 때 주석도 같이 만드는 이유는, “주석이 좋은가?”라는 철학 문제라기보다 모델이 ‘사람이 기대하는 산출물’을 가장 안전하게 맞추는 습관에 가깝습니다.

 

예를 들어, 대부분의 AI 모델은 인터넷 및 오픈소스에서 많이 본 코드 패턴을 학습하여 따라가는데 대부분은 다음과 같은 형식을 사용할 것입니다.

 

• 함수 위에 짧은 설명(JSDoc, docstring 등)
• 복잡한 로직 사이에 단계 주석

 

위와 같은 케이스가 많기 때문에 모델은 “코드만 던지면 불친절하다”는 분포를 학습합니다. 따라서, 주석을 사용하지 않는 케이스 보다 주석을 사용하는 케이스가 훨씬 더 많기 때문에 AI는 주석을 사용한다는 점을 알 수 있습니다.

 

---

 

 

👀 AI가 만들어내는 주석 특징 파헤치기

그렇다면 AI가 만들어내는 주석에는 어떠한 특징들이 있을까요? 과연 믿고 써도 될 정도로 AI가 일반적인 주석 사용 패턴을 따르고 있는지 한번 알아보도록 하겠습니다.

 

모든 언어가 마찬가지만 주석은 팀원, 그리고 코드를 읽는 사람들을 위해 작성하는 것이기 때문에 팀 간의 규칙을 만들어서 적용하는 것도 중요하지만 에디터(IDE)에서 지원이 되는 주석 포맷인지도 중요하다고 생각합니다. 이 부분이 결국 개발자들의 경험(DX)에 영향을 미칠 수 있기 때문에 대부분은 가장 일반적인 주석 컨벤션을 채택하여 사용합니다.

 

많이 쓰이는 언어 중 하나인 JS/TS의 가장 대중적인 주석 문서는 JSDoc/TSDoc입니다. 대부분의 에디터들은 표준 JSDoc 어노테이션을 이해해서 자동완성이나 hover 문서, 시그니처 도움말 등을 생성해 냅니다. 대부분의 AI들도 이 표준 문서에 맞게 주석을 생성해 내는 것을 볼 수 있습니다.

 

cursor 에디터에서 나타나는 interface props hover(왼쪽)와 함수 설명 hover(오른쪽)

 

다만, 프론트엔드의 경우 JSDoc이나 TSDoc에 존재하지 않는 React 컴포넌트의 경우에는 어떻게 주석을 작성해야 할까요? 만약 컴포넌트에 주석을 만들어달라고 요청하는 순간 AI는 혼란이 오기 시작할 것입니다. 어떨 때는 @property 어노테이션을 만들어서 사용하기도 하고 어떨 때는 컴포넌트를 일반적인 함수와 비슷하다고 생각해서 @param라는 어노테이션을 사용할 때도 있습니다.

 

왜냐하면 AI가 알고 있는 JSDoc에는 React 컴포넌트에 대해 주석 다는 방법에 대한 정의가 없기 때문이죠. 이 때문에 사람들은 프로젝트마다 또는 팀마다 각자만의 방법들과 포맷들을 사용하기 때문에 AI가 일관되지 않는 주석을 사용하면서 우리들에게 일부 혼란을 줄 수 있습니다. 예를 들어, 유명한 오픈소스 CSS 프레임워크 중 하나인 Material UI는 컴포넌트에 다음과 같은 포맷을 주석으로 사용합니다.

 

MUI 컴포넌트 주석 포멧 예시(Select)

 

위와 같은 상황에서는 사용하는 사람마다 코드 일관성이 붕괴될 수 있기 때문에 코드베이스가 어느 정도 잡히지 않은 상태에서는 AI 룰 파일에 규칙을 추가해 놓는 것이 좋습니다. 이런 식으로 일반적이지 않은 케이스들에 대해서는 팀원들과 공유하여 어떤 식으로 맞춰가면 좋을지 논의를 통해 룰 북을 완성시켜 혼란을 방지하는 것이 중요합니다.

 

---

 

✍️ 우리(Human)는 앞으로 주석을 어떻게 작성해야 할까?

"AI가 알아듣지 못하는 언어로 소통하는 레지스탕스들" - Nano Banana로 생성

 

저는 AI가 만들어내는 주석을 활용해도 괜찮다고 생각합니다. 실제로 최근 사내 디자인시스템을 구현하면서 AI가 만들어낸 주석을 보고 굉장히 잘 만들어진 오픈소스를 보는 듯한 느낌을 받았습니다.

 

물론 복잡한 알고리즘을 요구한 경우 저와의 대화내용을 바탕으로 이해하기 쉽도록 line-by-line으로 알고리즘을 설명할 때도 있었지만 이 주석들이 가독성을 헤친다거나 그런 느낌보다는 오히려 한국어로 주석이 작성되기 때문에 모국어가 주는 안정감으로 인해 DX가 높아지는 느낌을 전달받았습니다.

 

제가 읽기에 부족함이 없었다면 다른 사람들이 보기에도 괜찮을 것이므로 일부로 주석을 지우거나 하지 않아도 된다고 생각합니다. 이 부분이 조금 껄끄러우시다면 AI가 작성한 코드라는 것을 명시할 수도 있을 것 같습니다.

 

그럼에도 AI가 절대로 남길 수 없는 주석들이 있습니다. 바로 TODO, deprecated 같은 어노테이션인데요. 우리는 어쩔 수 없이 시간이 없어서 지금 당장 수정이 어려운 경우 또는 코드가 지저분해서 리팩토링 하고 싶은 경우 또는 다른 사람들에게 남기는 메시지 등 다양한 용도로 주석을 작성할 때도 있습니다.

 

또한 AI가 코드베이스 밖의 상황(예를 들어 팀 단위 또는 스쿼드 단위의 스프린트 회의 등)과 변화에 둔감하기 때문에 미래의 나에게 또는 다른 사람들에게 어떠한 메시지를 남겨놓고 싶은 경우에는 사람이 개입해서 주석을 작성할 수밖에 없습니다. 그래서 저는 아직까지는 다음과 같은 주석들은 사람의 손이 필요하다고 생각합니다.

 

사람이 남길 가치가 큰 주석

• “왜 이 선택을 했는지” (대안 대비 이유)
• “외부 제약/레거시/버그 회피” 기록
• “도메인 특성/고객 요구사항”
• TODO/deprecated 등의 메시지

 

---

 

🌠 정리하기

"AI와 인간의 화합" - Nano Banana로 생성

 

“AI가 만들어내는 주석 믿고 써도 될까?”라는 주제에 대해서 깊게 고민하게 된 배경은 AI가 사람의 영역에서 어디까지 침범하는 건가 싶은 회의감도 있었고 처음에는 AI가 만들어내는 주석에 왠지 모를 거부감 같은 게 들었었습니다. 그래서 한 번은 제 생각을 정리해보고 싶었고 이번 계기를 통해 제 스스로도 AI 주석에 대해 수용하게 되는 계기가 되지 않았나 싶습니다.

 

그리고 AI가 주석을 근본 없이 작성하는 것이 아니라 사용하고 있는 코드언어에 맞게 표준화된 가이드 포맷팅에 따라 주석을 작성하기 때문에 에디터에서도 편리하게 사용할 수 있고 생각보다 잘 만들어낸다는 생각도 들었습니다. 특히 혼자 개발하는 솔로 프리너나 인디해커 분들, 특히 비개발자 분들께는 주석이 일종의 유지보수 가이드라인이 될 수 있기 때문에 AI 주석을 적극 활용하시는 방향이 좋을 수도 있겠다는 생각도 듭니다.

 

평생 살면서 모든 언어, 모든 내장 함수를 항상 장기적으로 습득할 수 없다고 생각합니다. 특히, 인간은 망각의 동물이기 때문에 이전에 열심히 외워놓았던 함수나 로직들도 까먹기 마련입니다. 그러나, 한글이나 영어는 죽을 때까지 평생 사용하는 언어이므로 앞으로는 AI 주석도 열심히 활용해서 AI와 소통, 사람과 사람 간의 소통에 적극 활용해보고자 합니다.