[좋코vs나코] 제2편: "주석 없이는 해독 불가!" vs "코드가 곧 문서" - 주석의 올바른 활용법 💬

안녕하세요, 코딩 꿈나무 여러분! 🌱 오늘은 코드 작성 시 은근히 논쟁거리가 되는 '주석'에 대해 이야기를 나눠볼까요? 어떤 개발자분은 "주석 없이는 나중에 절대 이해 못 해요!" 😱 라고 외치는 반면, 또 다른 개발자분은 "잘 짠 코드는 그 자체가 문서입니다!" 😎

라고 자신만만하게 말씀하시죠. 과연 누구의 말이 맞을까요? 정답은… 둘 다 일리가 있다는 것입니다! 😉

핵심은 바로 주석을 '언제', '왜', '어떻게' 사용하느냐에 달려있습니다. 자, 그럼 지금부터 선배 개발자로서 주석의 A to Z를 쏙쏙 알려드리겠습니다! 🚀

반응형

❌ 이런 주석은 이제 그만! (나쁜 주석 예시)

코드를 깔끔하게 만들려다 오히려 더럽히는 주석들이 있습니다. 이런 주석들은 가독성을 해치고, 심지어 버그의 원인이 되기도 합니다. 😭

1. 당연한 코드 설명 (Captain Obvious 주석)

   // 사용자의 이름을 반환합니다.
   function getUserName(user) {
     return user.name;
   }
   

   🤔 어떤 점이 문제일까요? 코드를 읽을 줄 아는 사람이라면 누구나 이해할 수 있는 내용을 반복하는 것은 시간 낭비이자 화면 공간 낭비입니다. 이런 주석은 코드를 복잡하게만 만들고 아무런 가치도 제공하지 못합니다. "코드가 곧 문서"라는 말은 이런 경우에 딱 어울리죠!

2. # i 변수에 1을 더합니다.
   i = i + 1
   

3. 오해를 부르는 주석 (거짓말쟁이 주석)🤔 어떤 점이 문제일까요? 코드는 변경되었는데 주석이 그대로라면 어떻게 될까요? 💣 이는 정말 지양해야 할 상황입니다! 개발자는 주석을 믿고 코드를 이해하려 할 텐데, 잘못된 정보는 혼란을 야기하고 결국 버그로 이어질 수 있습니다. 주석을 달았다면, 코드 변경 시 반드시 함께 업데이트하는 습관을 들여야 합니다. (사실 이런 주석은 애초에 작성하지 않는 것이 나을 수도 있습니다!)

4. // 할인율을 10%로 고정합니다. (실제로는 5%로 변경되었지만 주석은 수정 안 됨)
   double discountRate = 0.05;
   

5. 주석 처리된 죽은 코드 (코드 공동묘지)🤔 어떤 점이 문제일까요? "나중에 혹시 사용할지도 모른다..."는 생각으로 남겨둔 주석 처리된 코드는 대부분 영원히 사용되지 않습니다. 🧟‍♂️ 이런 코드는 가독성을 떨어뜨리고, 코드를 이해하는 데 방해가 됩니다. 지금 당장 필요 없는 코드는 과감히 삭제하세요! 버전 관리 시스템(Git 등)이 과거의 코드를 안전하게 보관해주고 있으니 걱정하지 않으셔도 됩니다. 🚧

6. // function oldLogin(userId, userPassword) {
   //   // 예전 로그인 로직...
   //   // ...
   //   // 지금은 사용 안 함. 혹시 몰라 남겨둠.
   // }
   

7. 변경 의도를 알 수 없는 주석 (의미불명 주석)🤔 어떤 점이 문제일까요? "왜" 임시로 수정했는지, "언제" 원래대로 되돌려 놓을 것인지, "어떤 문제" 때문에 수정했는지 알 수 없다면 어떻게 될까요? 이런 주석은 혼란만 가중시킵니다. 차라리 커밋 메시지에 자세한 내용을 적거나, 이슈 트래커에 기록하는 것이 훨씬 바람직합니다.

8. # 임시로 수정함 - 김대리
   x = y * 2 # 원래는 y * 2.5 였음
   

✅ 이런 주석은 칭찬합니다! (좋은 주석 예시)

자, 그럼 어떤 주석이 우리에게 도움이 되는 좋은 주석일까요? 😊

1. '왜(Why)'를 설명하는 주석

   # 특정 브라우저(IE11)에서 발생하는 렌더링 이슈를 해결하기 위해
   # 부득이하게 강제로 리플로우를 유발합니다.
   element.style.display = 'none';
   element.offsetHeight; # 강제 리플로우
   element.style.display = '';
   

   💡 어떤 점이 좋을까요? 단순히 코드가 하는 일을 설명하는 것이 아니라, 그 코드가 존재해야 하는 이유, 특정 결정의 배경을 설명해줍니다. 이런 주석은 나중에 코드를 유지보수할 때 "이 코드는 왜 이렇게 작성되어 있지?"라는 의문을 해소해주고, 함부로 코드를 변경해서 생길 수 있는 문제를 예방해줍니다.
2. 코드는 '무엇을(What)' 하는지는 보여주지만, '왜(Why)' 그렇게 하는지는 설명하기 어려울 때가 많습니다.
3. 복잡한 로직이나 비즈니스 배경 설명

   // 사용자의 최종 등급은 구매 금액, 활동 점수, 특별 프로모션 적용 여부를
   // 종합하여 다음 규칙에 따라 결정됩니다:
   // 1. VIP: 구매 금액 100만원 이상 AND 활동 점수 500점 이상
   // 2. GOLD: 구매 금액 50만원 이상 OR 활동 점수 300점 이상 (VIP 제외)
   // 3. SILVER: 위 조건에 해당하지 않는 모든 고객 (특별 프로모션 대상은 GOLD로 승격)
   public UserGrade calculateUserGrade(User user, Promotion promotion) {
       // ... 복잡한 로직 구현 ...
   }
   

   💡 어떤 점이 좋을까요? 코드만 봐서는 파악하기 어려운 비즈니스 규칙이나 전체적인 그림을 제공해서, 개발자가 세부 코드에만 매몰되지 않고 큰 흐름을 이해하도록 도와줍니다.
4. 특히 도메인 지식이 필요하거나, 여러 단계를 거치는 복잡한 계산 로직은 주석으로 핵심을 요약해주면 이해하기 훨씬 수월해집니다.
5. API 문서화 주석 (Docstrings, JSDoc, JavaDoc 등)

   def add(a, b):
     """두 숫자를 더한 결과를 반환합니다.
   
     Args:
         a (int): 첫 번째 숫자.
         b (int): 두 번째 숫자.
   
     Returns:
         int: a와 b를 더한 값.
     """
     return a + b
   

   💡 어떤 점이 좋을까요? 이 코드가 어떤 파라미터를 받고, 무엇을 반환하며, 어떤 예외를 발생시킬 수 있는지 등을 명확히 알려줍니다. IDE에서는 이런 주석을 기반으로 코드 자동완성이나 도움말을 제공하기도 합니다. 📚
6. 함수, 클래스, 모듈 등의 사용법을 설명하는 주석입니다. 특히 다른 개발자와 협업하거나 라이브러리를 만들 때 필수적입니다!
7. TODO, FIXME 등의 표식

   // TODO: 현재는 사용자 ID만 사용하지만, 향후 다양한 인증 수단을 지원하도록 확장 필요 (JIRA-TASK-123)
   function authenticateUser(userId) {
       // ...
   }
   
   // FIXME: 특정 조건에서 null 포인터 예외가 발생할 수 있음. 원인 파악 및 수정 필요.
   if (user.profile.getAvatarUrl()) {
       // ...
   }
   

   💡 어떤 점이 좋을까요? "나중에 해야지" 하고 잊어버리는 것을 방지해주고, 팀 동료들에게도 해당 부분에 대한 주의를 환기시킬 수 있습니다. 🎯 종종 이슈 트래커 ID와 함께 작성하면 더욱 효과적입니다!
8. 지금 당장 해결하지는 못하지만, 나중에 개선해야 할 부분이나 수정해야 할 버그를 표시할 때 유용합니다.

🎯 핵심은 바로 이것입니다!

결국 주석의 핵심 원칙은 다음과 같습니다:

"코드로 의도를 명확히 표현하되, 코드가 스스로 말하지 못하는 부분(Why, 배경, 복잡한 요약 등)을 주석으로 보충하는 것입니다!"

좋은 변수명, 함수명, 명확한 로직 구조를 통해 코드 자체의 가독성을 높이는 것이 우선입니다. 하지만 그것만으로 부족할 때, 주석은 강력한 보조 도구가 될 수 있습니다.

자, 오늘부터는 "왜 이 주석을 쓰고 있는지" 한 번 더 고민해보시는 것은 어떨까요? 😊 그러면 여러분의 코드는 더욱 빛나게 될 것입니다. ✨ 다음 편에서 또 뵙겠습니다! 👋