Skip to main content

4장 주석

1. 📌 핵심 개념 정리

✅ 요약하기

1. 주석은 나쁜 코드를 보완하지 못한다.

나쁜 코드에 주석을 달지 마라. 새로 짜라.

코드에 주석을 추가하는 주된 이유는 코드 품질이 좋지 않기 때문이다. 깔끔하고 표현력이 풍부한 코드는 주석이 거의 필요 없으며, 주석으로 코드를 설명하려 할 시간에 코드를 개선하는 데 집중해야 한다. 주석은 코드의 실패를 의미하며, 유지보수가 현실적으로 어렵기 때문에 최소화해야 한다.

2. 코드로 의도를 표현하라!

코드만으로 의도를 설명하기 어려운 경우가 있을 수 있지만, 많은 경우 주석 대신 함수나 변수 이름, 코드 구조 자체로 의도를 명확히 할 수 있다. 주석으로 표현하려던 내용을 코드로 재작성하여 의도를 드러내는 것이 더 효과적이다.

  • 개선 전 (주석)
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags && HOURLY_FLAG) && (employee.age > 65))
  • 개선 후 (함수)
if (employee.isEligibleForFullBenefits())

3. 좋은 주석

드물게 좋은 주석도 존재하며, 특정 상황에서는 유용할 수 있다.

  • 법적인 주석: 저작권 정보나 라이선스 정보 등 법적으로 필요한 주석.
  • 정보를 제공하는 주석: 기본적인 정보 (반환 값, 인수의 형식 등)를 제공하는 주석. 가능하면 함수 이름 등으로 대체하는 것이 좋다.
  • 의도를 설명하는 주석: 코드의 의도나 배경, 결정 이유 등을 설명하는 주석. 특히 복잡한 로직이나 알고리즘의 의도를 명확히 할 때 유용하다.
  • 의미를 명료하게 밝히는 주석: 인수나 반환 값이 모호할 때, 그 의미를 명확히 설명하는 주석. 특히 외부 라이브러리나 수정 불가능한 코드에 유용하다.
  • 결과를 경고하는 주석: 코드의 특정 동작으로 인해 발생할 수 있는 경고나 주의사항을 알리는 주석 (예: 성능 문제, 스레드 안전 문제 등).
  • TODO 주석: 앞으로 해야 할 일이나 미완료된 부분을 표시하는 주석.

4. 나쁜 주석

대부분의 주석은 불필요하거나 오히려 코드 이해를 방해하는 나쁜 주석에 속한다.

  • 주절거리는 주석: 장황하고 불필요한 설명으로 가득 찬 주석, 코드 자체보다 이해하기 어려운 주석.
  • 같은 이야기를 중복하는 주석: 코드 내용을 그대로 반복하거나, 코드만으로 충분히 명확한 내용을 주석으로 다시 설명하는 경우.
  • 오해할 여지가 있는 주석: 부정확하거나 모호한 정보를 담고 있어 오히려 혼란을 야기하는 주석. 시간이 지남에 따라 코드와 주석이 불일치하게 될 위험이 크다.
  • 의무적으로 다는 주석: 모든 함수나 변수에 기계적으로 작성해야 하는 Javadoc 주석 등. 코드 가독성을 떨어뜨리고 불필요한 정보를 추가한다.
  • 이력을 기록하는 주석: 코드 변경 이력을 모듈 헤더에 기록하는 주석. 버전 관리 시스템으로 충분히 대체 가능하다.
  • 있으나 마나 한 주석: 너무 당연한 내용을 설명하거나 새로운 정보를 제공하지 못하는 주석 (예: // 기본 생성자, // 숫자를 저장).
  • 무서운 잡음: Javadoc 이나 위치 표시 주석 등, 코드의 가독성을 해치는 시각적 잡음.
  • 위치를 표시하는 주석: // Actions //////////////////// 와 같이 특정 위치를 표시하기 위한 주석. 코드 탐색을 방해하고 가독성을 저하시킨다.
  • 닫는 괄호에 다는 주석: } 괄호 옆에 변수명이나 함수명을 주석으로 다는 행위. 함수를 작게 만들면 불필요하다.
  • 공로를 돌리거나 저자를 표시하는 주석: 누가 작성했는지 표시하는 주석. 버전 관리 시스템이 이 역할을 대신한다.
  • 주석으로 처리한 코드: 과거에 작성되었으나 현재는 사용하지 않는 코드를 주석 처리해 둔 경우. 소스 코드 관리 시스템을 활용하고 삭제하는 것이 깔끔하다.
  • HTML 주석: 소스 코드 내 HTML 주석은 가독성을 매우 떨어뜨린다.
  • 전역 정보: 코드의 지역적인 내용이 아닌 시스템 전반적인 정보를 담는 주석. 코드 변경 시 주석이 함께 업데이트되지 않을 가능성이 높다.
  • 너무 많은 정보: 코드의 핵심 의도와 무관한 장황한 설명이나 역사적 배경 등을 담은 주석.
  • 모호한 관계: 주석과 코드가 명확하게 연결되지 않아 주석이 어떤 코드를 설명하는지 불분명한 경우.
  • 함수 헤더 주석 (비공개 코드): 짧고 명확한 함수에는 헤더 주석이 불필요하다. 특히 비공개 코드의 경우 Javadoc 형태의 헤더 주석은 과도하다.

2. 🤔 이해가 어려운 부분

🔍 질문하기

  1. "코드로 의도를 표현하라"라는 원칙의 한계

    • 어려웠던 부분: 코드로 대부분의 의도를 표현할 수 있다고 하지만, 복잡한 비즈니스 로직이나 도메인 지식이 필요한 경우에도 이 원칙이 적용될 수 있는지 궁금하다.

  2. 코드로 의도를 표현하라!

    • 어려웠던 부분: 가능하면 주석 대신 함수 이름으로 표현하라는 저자의 의견에 완전히 동의하기 어려웠다.
    • 궁금한 점: 많은 개발자가 함수 이름을 짓는 데 많은 시간을 들이는데 주석까지 최소화하며 코드를 작성하면 코드 작성 시간이 더 늘어나는 것은 아닐까?

  3. 오해할 여지가 있는 주석

    • 어려웠던 부분: 예시로 제시된 주석(// this.closed가 true일 때 반환되는 유틸리티 메서드다.)과 코드의 관계 설명이 명확하게 와닿지 않았다.
    • 궁금한 점: 제시된 코드 예시의 주석이 왜 오해의 여지가 있는 주석인지 더 자세한 설명이 필요하다.
     // this.closed가 true일 때 반환되는 유틸리티 메서드다.
 // 타임아웃에 도달하면 예외를 던진다.
 public synchronized void waitForCloase(final long timeoutMillis) throws Exception {
     if(!closed)
     {
         wait(timeoutMillis);
         if(!closed)
             throw new Exception("MockResponseSender could not be closed");
     }
 }

  4. Javadocs 주석

    • 어려웠던 부분: Javadocs 주석을 어느 정도로 작성해야 적절한지, 평소 사용하는 Javadocs 주석은 적절한 수준인지 궁금하다.
    • 궁금한 점: 함수명과 변수명으로 기능 파악이 가능하더라도 Javadocs 주석이 기능 설명을 더 명확하게 제공하는 경우가 있는데, 이런 경우 주석을 사용하는 것이 괜찮은가?
    • 논의 하기: 함수 자체로 기능이 잘 설명되는 경우 vs 주석의 설명이 더 효과적인 경우

  5. 의도를 설명하는 주석

    • 궁금한 점: 좋은 주석에서 '의도를 설명하는 주석'과 나쁜 주석의 차이는 무엇인가?

3. 📚 참고 사항

📢 논의하기

  1. 코드만으로 표현하기 어려운 경우, 주석을 적절히 활용하는 방법은?

    • 주제: 코드만으로 표현하기 어려운 복잡한 로직이나 도메인 지식이 필요한 경우, 어느 수준까지 주석을 달아야 적절할까? 주석을 효과적으로 활용하는 방법은 무엇일까?

  2. 주석 대신 코드로 의견을 표현하는 것이 오히려 더 어려운 방법은 아닐까?

    • 주제: 함수명, 변수명 짓기와 코드 구조 개선 등 코드로 의도를 표현하는 것이 주석보다 더 많은 시간과 노력이 필요할 수 있다. 코드 품질 개선과 개발 효율성 사이의 균형점을 어떻게 찾아야 할까?

  3. 좋은 주석에서의 의도를 설명하는 주석과 나쁜 주석과의 확실한 차이는 무엇인지

    • 주제: '의도를 설명하는 좋은 주석'과 '나쁜 주석'의 경계가 모호하게 느껴질 수 있다. 어떤 주석이 좋은 '의도를 설명하는 주석'이며, 어떤 경우에 나쁜 주석으로 분류될 수 있을까? 단순한 코드 설명이 아닌, 결정의 배경이나 맥락을 설명하는 주석은 어떤 기준으로 판단해야 할까?

  4. 부수 효과 최소화:

    • 주제: "시간적인 결합이나 순서 종속성을 초래한다"는 '부수 효과'의 의미는 무엇인가? 함수가 예측 가능한 결과를 보장하기 위해 외부 상태를 변경하지 않아야 한다는 원칙은 어떻게 적용해야 할까?
Back to top