[클린코드] 4장 : 주석

• 주석은 왜 사용하는가
  • 몇몇 주석은 설명 혹은 기타 정보 전달을 위해 작성한다.
  • 하지만 정말 코드를 잘 작성한다면 주석은 필요하지 않다.
    
    
• 주석은 나쁜 코드를 보완하지 못한다.
  • 일반적으로 코드가 명확히 설계되지 않았을 때 주석을 사용한다. 하지만 이는 주석을 달기보다 더욱 코드를 명확히 설계하며 깔끔하게 코드를 짜야한다.
    
    
• 코드로 의도를 표현하라
  • 위와 같은 이야기이다. 주석을 통해 설명하고자하는 것은 코드로 전부 기능을 보여주지 못해서 그렇다.
  • 함수 이름 및 변수명을 잘 작성하여 주석을 줄이자.
    
    
• 그럼에도 주석이 필요한 경우가 있다. 물론 그렇게 주석이 사용된다고 해서 코드를 잘 짰다는 것은 아니다. 주석은 적을수록 좋다. 필요할 때 사용되는 좋은 주석과 그렇지 않은 나쁜 주석을 살펴보자.
  
  
• 좋은 주석
  • 법적인 이유로 들어가는 주석 (저작권 정보 등)
  • 정보를 제공해주는 주석 (함수의 기본적인 정보 등)
  • 의도를 설명하는 주석 (개발자의 결정이 개입되어 그 의도를 설명 혹은 표준 라이브러리를 사용한 경우 등)
  • 경고를 제공하는 주석 (실행 결과 및 오류 등을 미리 경고하는 주석)
  • TODO, FIXME 주석
  • 중요성을 강조하는 주석 (가볍게 여겨져 실수로 지우거나 수정하면 안되는 부분 등)
  • Javadocs (공개 API 및 공통 모듈에서의 javadocs)
  • annotation (@Deprecated 등)
    
    
• 나쁜 주석
  • 주절거리는 주석 (개발자가 공을 충분히 들이지 않고 자기만 알아듣도록 주절거린 주석)
  • 같은 내용을 중복 설명하는 주석, 중복은 개발자에게 유해하다.
  • 오해할 여지가 있는 애매한 주석
  • 의무적으로 다는 주석 (아무 의미 없이 의무로 인해 다는 메소드 인자 등)
  • 이력 기록 주석, git을 사용하자.
  • 있으나마나 쓸모없는 주석
  • 함수로 표현할 수 있는 주석, 함수명을 공들여 쓰자.
  • 주석으로 처리한 코드, 필요 없으면 지우자
  • 공로를 돌리거나 저자를 표시하는 주석, git을 사용하자
    
    

결론

주석은 최대한 존재하지 않는 것이 좋다. 꼭 필요한 경우라면 작성을 하는 것이 좋지만, 이는 법적인 이유의 주석 외에는 그렇게 중요해보이지 않는다. 최대한 코드에서 나타나게 코드를 짜는 연습을 하는 것이 좋다고 판단하였다.

업무 중에 적용할만한 내용

좋은 주석 중에는 의도를 밝히는 주석, TODO 정도 사용 중이다. 특히 TODO를 남기는 것을 좋아하기 때문에, 이게 좋은 코드라는 내용이 정말 반가웠다. 나아가 FIXME 메소드를 처음 보았다. 이 것도 앞으로 사용해볼 생각이다.

나쁜 주석 중에는 의무적으로 다는 주석을 자주 사용한다. 언제나 코드는 공유되어야된다는 생각을 한다. 그렇기 때문에 이 함수를 타인이 보기 편하게 작성하려면 메소드 인자를 작성해야한다는 생각을 하였는데, 이 것이 의무적으로 다는 나쁜 주석이라는 것을 보고 충격을 먹었다. 앞으로는 꼭 중요하지 않다면 메소드 인자 주석을 줄여볼 예정이다.

Written by 상 한규

nic6@naver.com