[클린 코드] 주석(1)

주석은 코드를 부연 설명해주는 역할을 한다.
하지만 주석으로 좋지 않은 방법으로 짜인 코드를 보완하진 못한다.

표현력이 풍부하고 깔끔하게 짜여진 코드는 주석이 사실상 거의 필요가 없다.
간단한 예를 들어보자

//직원에게 복지 혜택을 받을 자격이 있는지 확인한다.  
if((employ.flags & HOURLY_FLAG) && (employee.age > 65));  

if(employ.isEligibleForFullBenefits());

 

위 두 if문은 같은 비교를 하지만 누가 봐도 주석을 달지 않고도 코드만으로 의도를 분명히 할 수 있다.
이와 같이 대다수의 경우 주석으로 만들려는 설명을 함수로 풀어 표현하기에 충분하다.

하지만 특정한 경우에는 주석이 필요할 순 있다.

좋은 주석

• 법적인 주석
  - 특정 회사가 정한 구현 표준에 맞춰 법적인 이유로 특정 주석으로 넣으라고 명시하는 경우이다.
  각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 반드시 따라줘야 한다.
• 정보를 제공하는 주석
  - 때로는 기본적인 정보를 주석으로 제공하면 편리하다.
  다음 코드에 주석은 추상 메서드가 반환할 값을 정의한다.

//테스트 중인 Responder 인스턴스를 반환  
protected abstract Responder reponderInstance();  

하지만 위에서 말했듯이 함수 이름을 responderBeingTested로 풀어 작성하면 굳이 주석이 필요하진 않다.

• 의도를 설명하는 주석
  - 코드 구현을 이해하게 도와주는 선을 넘어 코드 작성 방향 결정에 깔린 의도를 설명할 수 있다.
• 의미를 명료하게 밝히는 주석
  - 일반적으로 인수나 반환값을 명료하게 표현하도록 만들면 더 좋지만, 인수나 반환 값이 표준 라이브러리 거나
  변경하지 못하는 코드라면 도움을 주는 주석을 만들 수 있다.
  물론 잘못된 이해로 잘못된 주석을 잘아 놓는 위험도 따를 순 있다.
  이것이 의미를 명료히 밝히는 주석이 필요한 이유인 동시에 위험한 이유가 된다.
  그러므로 먼저 주석이 필요 없는 코드로 작성이 불가능할지 고민하고 여의치 않다면 정확히 달아야 한다.
• 결과를 경고하는 주석
  - 협업하는 프로그래들에게 결과를 경고할 목적으로 주석을 사용할 수 있다.
  테스트를 위한 코드인 경우 @Ignore 속성을 사용하여 테스트 케이스를 끌 수 있다.
  @Ignore("실행에 많은 시간이 걸림")
  하지만 JUnit4가 나오기 전에는 메서드 이름 앞에 _기호를 붙이는 게 관례였다고 한다.
  아래 코드는 주석이 적절한 예이다.

public static SimpleDateFormate makeStandardHttpDateFormat(){ 
  //SimpleDateFormat은 스레드에 안전하지 않음. 
  //따라서 각 인스턴스를 독립적으로 생성해야 함. 
   SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z"); 
   return df;
  }

• TODO 주석
  - 프로그래머가 앞으로 해야 할 일 또는 구현해야 할 부분을 //TODO 주석을 사용하여 남기면 알아보기 쉽다.
  보통은 필요하다 판단하지만 당장 구현하기엔 어려움이 따를 때 기술한다.
• 중요성을 강조하는 주석
  - 대수롭지 않다고 여겨질 수 있는 무언가의 중요성을 강조할 수 있다.

//여기서 trim을 사용해 공백을 잘라줘야 한다. 
//trim 미수행시 다른 문자열로 인식함. 
String itemCount = match.group(5).trim(); 
...

• 공개 API에서 Javadocs
  - 표준 자바 라이브러리에서 사용한 Javadocs는 유용하게 쓰인다.
  이 처럼 공개 API를 구현한다면 반드시 Javadocs도 함께 작성해주도록 하여 보는 사람의 이해를 도울 수 있다.
  하지만 Javadocs 역시 오도되거나 잘못 위치하면 위험성을 내재하게 되니 주의가 필요하다.