[클린 코드] 4장 - 주석

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

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.

우리가 할 일은 주석으로 해결하려는 것이 아닌, 근본적으로 코드가 알아보기 힘들다는 것을 고쳐야한다.

코드로 의도를 표현하라!

확실히 코드만으로 의도를 설명하기 어려운 경우가 존재한다.

if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) {...}

하지만 몇 초만 더 생각하면 코드로 대다수 의도를 표현할 수 있다.

if (employee.isEligibleForFullBenefits()) {...}

따라서 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

좋은 주석

그렇다면 주석은 아예 필요 없는가? 좋은 주석이란 무엇일까?

아래와 같은 주석들은 필요하거나 유익하다.

• 법적인 주석
  • 때로는 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시한다.
  • 모든 조항과 조건을 열거하는 대신에, 가능하다면 표준 라이센스나 외부 문서를 참조하는 것이 좋다.
• 정보를 제공하는 주석
  • 때로는 기본적인 정보를 주석으로 제공하면 편리하다.
  • 물론 가능하면 코드로 나타내는 것이 좋다.
• 의도를 설명하는 주석
  • 코드만으로 저자의 의도가 불분명할 수 있으면 주석을 사용하여 알려도 좋다.
• 의미를 명료하게 밝히는 주석
  • 때로는 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다.
  • 예를 들어 asserTrue(a.compareTo(a) == 0); // a == a
• 결과를 경고하는 주석
  • 다른 개발자에게 결과를 경고할 목적으로 주석을 사용할 수 있다.
• TODO 주석
  • '앞으로 할 일'을 TODO 주석으로 남겨놓으면 편리하다.
  • 최신 IDE는 TODO 주석을 찾아주는 기능을 가지고 있다.
• 중요성을 강조하는 주석
  • 자칫 대수롭지 않다고 여겨질 무언가의 중요성을 강조할 때 사용해도 좋다.
• 공개 API에서 Javadocs
  • 공개 API를 구현한다면 반드시 훌륭한 Javadocs를 작성한다.

나쁜 주석

대다수 주석이 이 범주에 속한다.

허술한 코드를 지탱하거나, 엉성한 코드를 변명하거나, 미숙한 결정을 합리화하는 등 개발자가 주절거리는 독백에서 크게 벗어나지 못한다.

나쁜 주석은 다음과 같다.

• 주절거리는 주석
  • 주석의 내용이 이해가 안되어 독자와 제대로 소통하지 못하는 주석이다.
• 같은 이야기를 중복하는 주석
  • 주석이 코드보다 더 많은 정보를 제공하지 못한다.
  • 코드만 지저분하고 정신 없게 만드니 사용하지 말자.
• 오해할 여지가 있는 주석
  • 의도는 좋았으나, '살짝 잘못된 정보'로 인해 독자는 고통받을 수 있다.
• 의무적으로 다는 주석
  • 모든 클래스, 함수에 Javadocs를 다는 경우이다.
  • 심하면 모든 변수에 주석을 달기도 한다.
• 이력을 기록하는 주석
  • 모듈을 편집할 때마다 모듈 첫머리에 주석을 추가하는 관례가 있다.
  • 요즘에는 형상관리 툴에서 누가 커밋했는지 확인할 수 있다.
• 있으나 마나 한 주석
  • 예를 들어 기본 생성자에 // 기본 생성자 주석을 다는 경우가 있다.
  • 또 예를 들면 // 이 부분 구현이 정말 어려웠다. 도 있다. (나도 대학생 때...)
• 무서운 잡음
  • 때로는 의미 없는 Javadocs도 문서를 제공해야 한다는 잘못된 욕심으로 탄생한 잡음일 뿐이다.
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
  • 코드로 승부하자.
• 위치를 표시하는 주석
  • 때때로 개발자는 소스 파일에서 특정 위치를 표시하려 주석을 사용한다.
  • 일반적으로 가독성만 낮추는 경우가 많다.
• 닫는 괄호에 다는 주석
  • while 문 끝에 // while을 달거나, try 문 끝에 // try를 달거나 하는 경우이다.
  • 중첩되어 보기 힘들다면, 구조를 개선하자.
• 공로를 돌리거나 저자를 표시하는 주석
  • // 릭이 추가함과 같은 경우이다.
• 주석으로 처리한 코드
  • 주석으로 처리한 코드는 다른 개발자가 지우기를 주저한다.
  • 형상관리 툴이 모든 것을 기억해주니 그냥 삭제하자.
• HTML 주석
  • HTML 주석은 IDE에서조차 읽기 어렵다.
• 전역 정보
  • 주석을 달아야 한다면 근처에 있는 코드만 기술하라.
  • 함수 자체가 전혀 통제하지 못하는 정보를 적을 필요 없다.
• 너무 많은 정보
  • 주석에다 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓지 마라.
• 모호한 관계
  • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.
  • 주석 자체가 다시 설명을 요구하면 안타깝기 그지없다.
• 함수 헤더
  • 짧고 한가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.
• 비공개 코드에서 Javadocs
  • 공개 API는 Javadocs가 유용하지만, private이라면 굳이...?