Clean Code 짜기5

-주석  //   /**/

 

복잡하고 주석이 많이 달린 코드보다

표현력이 풍부하고 깔끔하고 주석이 거의 없는 코드가 더 좋다

코드만으로 의도를 표현하기 어려운경우 주석을 달아야 한다.

 

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

----

if (employee. isEligibleForFullBenefits())

 

위 두 코드를 보면 코드로 의도를 표현하는데 의도가 많은경우

주석으로 달려는 설명을 함수로 만들어 표현한 것이다.

 

 

 

기본적인 정보를 주석으로 제공하면 편리하다

 

// 테스트 증인 Responder 인스턴스를 반한한다.
protected abstract Responder responderInstance();

 

위 코드의 주석은 추상 메서드가 반환할 값을 알려주는 주석이다.

위 코드에서 조금 더 변경하면 함수 이름을 responderBeingTested로 바꾸면 

주석이 필요 없어진다.

 

 

 

의도를 설명하는 주석으로 코드를 이해하게 도와줄수 있다.

public int compareTo(Object o)
 {
   if(o instanceof WikiPagePath)
   {
      WikiPagePath p = (WikiPagePath) o;

      String compressedName = StringUtil.join(names, "");
      String compressedArgumentName = StringUtil.join(p.names, "");
      return compressedName.compareTo(compressedArgumentName) ;

    }
    return 1; // 오른쪽 유형이므로 정렬 순위가 더높다.
 }

결과값 리턴에 깔린 의도까지 주석으로 알려줄수 있다.

 

 

 

 

TODO주석으로 앞으로 할 일을 메모해두면 좋다

 

// TODO-MdH 현재 필요하지 않다.
// 체크아웃 모델을 도입하면 함수가 필요 없다.
protected Versionlnfo makeVersion() throws Exception 
{
    return null;

}

주기적으로 TODO주석을 점검해 필요없는 주석은 없애는게 좋다.

 

 

 

 

아래의 코드는 주석으로 코드를 지저분하게 만든다.

public abstract class ContainerBase 
implements Container, Lifecycle, Pipeline,
MBeanRegistration, Serializable {

/ ** 

* 이 컴포넌트의 프로세서 지연값
*/
protected int backgroundProcessorDelay = -1;

/  ** 
* 이 컴포넌트를 지원하기 위한 생명주기 이벤트
*/
protected LifecycleSupport lifecycle = 
new LifecycleSupport(this);
/ **  
* 이 컴포넌트를위한 컨테이너 이벤트 Listener
*/
protected ArrayList listeners = new ArrayListO
/ ** 
* 컨테이너와 관련된 Loader 구현
*/
protected Loader loader = null;

/ ** 
* 컨테이너와 관련된 Logger 구현
*/
protected Log logger = null;
/  ** 
* 관련된 logger 이름
*/
protected String logName = null;

/ ** 
* 컨테이너와 관련된 Manager 구현
*/
protected Manager manager = null;
/**
* 컨테이너와관련된 Cluster 
*/
protected Cluster cluster = null;

....

이와 같이 중복되고 코드의 기록이라는 목적에는 기여하지 못하는주석을 사용하지 않도록 하자.

 

 

 

있으나 마나 한 주석은 달지 않는게 좋다.

너무 당연한 사실을 언급해서 새로운 정보를 제공하지 못하는 주석은 표기하지 않도록 하자

 

/*

* 기본생성자

*/

protected AnnualDateRule(){

}

 

/** 월 중 일자 */

  private int dayOfMonth;

 

이렇게 코드만으로 확인이 가능한대, 주석으로 중복적인 정보를 제공해주지 않아도 된다.

 

 

 

주석으로 처리한 코드는 팀단위로 작업을 할때 다른 사람이 중요하다고 생각할 수 있어

코드를 지우기 주저하게 된다.

그래서 사실상 쓸모없는 코드인대도 지우지 못하고 남아있는 경우가 있다.

InputStreamResponse response = new InputStreamResponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
//InputStream resultsStream = formatter.getResultStream();
//StreamReader reader = new StreamReader(resultsStream);
//response.setContent(reader.read(formatter.getByteCount()));

이렇게 주석처리코드는 꼭필요하다면 주석으로 중요도를 명시해두자.

 

 

 

함수나 변수로 표현이가능하면 주석을 달지말고 코드로 표현을 하도록 하는게 좋다.

 

 

 

 

 

 

참고한 책

클린 코드 (Clean Code)