AI 주석 작성의 약속 (그리고 위험)

아, 손쉽게 문서를 작성할 수 있다는 달콤한 유혹! 코드 주석을 자동으로 생성해 준다는 AI 도구들이 마치 JavaScript 프레임워크처럼 쏟아져 나오고 있습니다. 아이디어는 간단합니다. 개발자의 업무 부담을 줄이고, 코드 유지 관리성을 개선하고, 전반적으로 문서화가 잘 된 소프트웨어의 황금기를 열겠다는 것입니다. 현실은요? 실제 코드를 가리는 장황하고 종종 의미 없는 설명의 쓰나미일 뿐입니다.

솔직히 말해서, 대부분의 코드 주석은 이미 엉망입니다. 코드를 그대로 따라 하거나('i = i + 1; // i 증가'), 끔찍할 정도로 오래되었거나, 고대 수메르어를 전공한 박사 학위가 있어야 해독할 수 있을 정도로 난해합니다. 그렇다면 이미 흐릿한 이 환경에 AI를 풀면 어떻게 될까요? 더 끔찍한 주석이 더 많이 생성될 뿐입니다. 단지 규모가 커졌을 뿐이죠.

문제: 장황함의 소용돌이

핵심 문제는 현재 AI 주석 생성기가 품질보다 양을 우선시한다는 것입니다. 모든 것을 설명하는 것을 목표로 하므로 다음과 같은 주석이 생성됩니다.


// 이 함수는 숫자 배열을 입력으로 받아 배열에 있는 모든 숫자의 합계를 반환합니다.
function sumArray(numbers) {
  // 합계를 0으로 초기화합니다.
  let sum = 0;
  // 숫자 배열을 반복합니다.
  for (let i = 0; i < numbers.length; i++) {
    // 현재 숫자를 합계에 더합니다.
    sum += numbers[i];
  }
  // 합계를 반환합니다.
  return sum;
}

축하합니다, AI! 코드가 하는 일을 완벽하게 설명했지만 왜 하는지는 설명하지 않았습니다. `sum += numbers[i]`가 무엇을 하는지 모르는 개발자는 애초에 코드를 작성하면 안 됩니다.

이것은 도움이 되는 것이 아니라 적극적으로 해롭습니다. 코드를 복잡하게 만들어 중요한 부분을 읽고 이해하기 어렵게 만듭니다. 인지 부하를 증가시켜 개발자가 필요한 실제 통찰력을 찾기 위해 엄청난 양의 텍스트를 헤쳐나가도록 강요합니다. 마치 누군가가 끊임없이 당신의 삶을 해설하는 것과 같습니다. '이제 커피 잔을 잡으려고 합니다. 이제 한 모금 마시려고 합니다. 이제 타서 얼굴을 찡그리고 있습니다.'

해결책: 상황 인식 AI, 또는 그냥...훌륭한 개발자?

그렇다면 해결책은 무엇일까요? AI에게 유머 감각을 가르치는 것(훨씬 더 냉소적이고 도움이 되지 않는 주석으로 이어질 것이라고 생각합니다)은 제쳐두고, 상황에 집중해야 합니다. AI는 코드의 더 넓은 목적, 현재 형태로 이어진 설계 결정, 개발자가 알아야 할 잠재적인 함정을 이해해야 합니다.

다음은 유용한 AI 생성 주석의 예입니다(단, `sumArray`가 더 큰 재무 계산의 일부라고 가정). *이것은 한국어 예시로 변경된 주석입니다.*


// sumArray: 거래의 총 가치를 계산합니다.
// 참고: 이 함수는 배열의 모든 숫자가 원화(KRW)로 되어 있다고 가정합니다.
// 다른 지역의 거래를 처리하는 경우 상위에서 통화 변환이 처리되었는지 확인하십시오.
function sumArray(numbers) {
  let sum = 0;
  for (let i = 0; i < numbers.length; i++) {
    sum += numbers[i];
  }
  return sum;
}

차이점이 보이시나요? 명백한 것을 설명하는 대신 중요한 가정(통화)을 강조하고 잠재적인 문제에 대한 지침을 제공합니다. 이것은 개발자의 시간을 절약하고 버그를 방지하는 데 도움이 되는 정보입니다.

고품질의 사람이 작성한 주석으로 AI를 훈련시키십시오: 쓰레기가 들어가면 쓰레기가 나옵니다. AI가 유용한 주석을 생성하기를 원한다면 좋은 주석의 예를 제공하십시오. 영감을 얻기 위해 문서화가 잘 된 오픈 소스 프로젝트를 살펴보십시오.
'무엇'이 아닌 '왜'에 집중하십시오: AI는 코드가 하는 일을 설명하는 것이 아니라 코드 뒤에 숨겨진 이유를 설명해야 합니다. 이를 위해서는 코드의 목적과 상황에 대한 더 깊은 이해가 필요합니다.
개발자가 AI 생성 주석을 편집하고 개선할 수 있도록 허용하십시오: AI는 최종 단어가 아니라 시작점이 되어야 합니다. 개발자는 주석이 정확하고 유용한지 확인하기 위해 주석을 쉽게 편집하고 개선할 수 있어야 합니다. 약간 멍청한 AI와 함께 페어 프로그래밍한다고 생각하십시오.
간단한 기능에 대해서는 AI 주석 작성을 비활성화하는 것을 고려하십시오: 때로는 최고의 주석이 아무 주석도 없는 것입니다. 코드가 자명한 경우 불필요한 설명으로 코드를 복잡하게 만들지 마십시오.

가혹한 진실

어쩌면, 단지 어쩌면 해결책은 더 나은 AI가 아니라 더 나은 개발자일 수 있습니다. 명확하고 간결하며 상황을 인식하는 주석의 중요성을 이해하는 개발자. 코드를 작성할 뿐만 아니라 시간을 내어 코드를 설명하는 개발자. 더 이상 관련이 없는 경우 주석을 삭제하는 것을 두려워하지 않는 개발자.

AI가 소프트웨어 개발의 뉘앙스를 진정으로 이해할 수 있을 때까지는 코드 문서화를 위해 인간 지능(과 건전한 상식)에 의존하는 것이 좋습니다. 결국, 잘 만들어진 주석은 미래의 자신(과 동료)에게 보내는 연애 편지입니다. AI가 그것을 장황하고 일관성 없는 성명으로 바꾸지 않도록 하십시오.

따라서 AI 생성 주석을 맹목적으로 받아들이기 전에 자문해 보십시오. 실제로 코드베이스를 개선하고 있습니까, 아니면 쓸모없는 장황함의 바다에 빠져들고 있습니까? 대답은 종종 후자일 것이라고 생각합니다.