[클린 코드] 4장. 주석

1. 주석은 최대한 쓰지 말자

 코드로 충분히 개발 의도를 설명하지 못하기 때문에 주석을 남기게 되는 것이다. 의미있는 변수명, 메소드를 사용하는 것으로도 의미를 파악하기 쉽다. 또한 코드는 컴파일되기 때문에 변화가 반영되지만, 코드는 텍스트일뿐이라 변화 추적에 취약하므로 오해를 불러 일으킨다.

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && employee.age > 65)) {}

// 주석 대신 의미있는 이름을 지어 해결
if (employee.isEligibleForFullBenefits()) {}

 

2. 좋은 주석을 쓰자

 구현에 대한 정보를 제공한다. 문자열 패턴 처럼 알아보기 힘든 포맷에 대해서 주석을 남긴다. 의도와 중요성을 설명하는 주석은 필요하다.  특정 의미를 포함하는 주석을 사용하는 것도 좋다.

// 스레드를 많이 생성하여 시스템에 영향을 끼쳐 테스트를 만들도록 함
for (int i = 0; i < 25000; i++) {
	SomeThread someThread = ThreadBuilder.builder().build();
}

// 유저로부터 입력받을 값을 저장할 때 trim으로 공백제거 필요
String userName = userNameInput.trim();

 // TODO : 지금은 해결하지 않지만 나중에 해야할 일을 미리 적어둘 때

 // FIXME : 문제가 있지만, 당장 수정할 필요는 없을 때  

 

3. 주석보다 annotation 을 쓰자

 annotation : 코드에 대한 메타 데이터로, 코드의 실행 흐름에 간섭을 주기도하고, 주석처럼 코드에 대한 정보를 줄 수도 있다. 

@Deprecated : 컴파일러가 warning을 발생시킴. 예를들어 클래스A 위에 @Deprecated 를 붙이면, 어디선가 클래스A를 사용할 때 warning을 발생시키면서 이 클래스를 사용하지 않으면 좋게다는 메세지를 띄운다.

@NotThreadSafe : ThreadSafe하지 않음을 나타냄. 

 

4. JavaDoc 문법

 JavaDoc이란 Java 코드에서 API 문서를 HTML 형식으로 생성해주는 도구이다. 장점은 IDE Reader Mode (IDE에서 볼때 슬래시, 에스크리터(*) 을 제외하고 오직 텍스트 내용만 볼 수 있다.)

/**
 * This is a JavaDoc
 */
 
 /**
  * <클래스 레벨> Hero is the main entity. We will be using to . . .
  * Please see the {@link com.baeldung.javadoc.Person} class for true identity
  * @author Captain America
  */
 public class SuperHero extends Person {
     /**
      * <필드 레벨> The public name of a hero that is common knowledge
      */
     private String heroName;
     
     /**
      * <메소드 레벨>
      * <p>메소드에 대한 간단한 설명
      * <a href="http://www.supermanisthegreatest.com">Superman!</a>
      * </p>
      * @param incomingDamage the amount of incoming damage
      * @return the amount of health hero has after attack
      * @see <a href="http://www.link_to_jira/HERO-402">HERO-402</a>
      * @since 1.0
      */
      public int successfullyAttacked(int incomingDamage) {
          return 0;
      }
 }

- {@line} : 원하는 클래스로 이동할 수 있는 기능

- <p><a></a></p> : JavaDoc은 HTML 로 만들어지기 때문에 해당 문법도 이용 가능하다.

- @param : 메소드에 들어오는 인자에 대한 설명

- @return : 메소드의 결과 값이 무엇인지 설명

- @see : 참고할 것

- @since : 버전