Here is Dragon

주석(코멘트)에 대한 대부분의 책은 단 한마디로 요약할 수 있다.
 "주식을 충실하게 달아라"

이는 다른말로 대부분의 프로젝트에는 주석이 충실하지 않다는 반증이고 주석 다는게 쉽지 않다는 말이기도 하다. 사실 좋은 코드와 나쁜 코드를 구분할 수 있는 것처럼 주석에도 좋은 주석과 나쁜 주석이 있다.

주석 안에는 무엇이 들어갈까 ? 주석을 달때 주의점은 아래와 같다 .

 - 어떻게가 아니라 왜를 기술하라 이를테면
    틀린예) GlbWLRegistry에 있는 WidgetList 구조를 업데이트 한다.
    라고 주석을 달아서는 안된다. 왜냐하면 그 내용은 코드안에 박혀 있기 때문이다. 따라서 "왜" 이렇게 코드를 작성했는지에 대해 주석을 달아야 한다. 
    바른예) 나중을 위해서 widget 정보를 캐시함 O


 - 코드를 묘사하지 마라
    틀린예) i++ ; // increment i
    DRY의 원칙은 단순히 코드끼리의 중복만을 의미하는 것은 아니다. 위 틀린예는 옆의 코드와 주석이 중복되기 때문에 DRY 원칙을 위배한 것이다. 코드와 중복되는 내용을 다시 코멘트로 쓰지 말아라. 


 - 코드를 대신하지 마라
    나쁜예) // 이 변수는 foo 클래스에 의해서만 접근해야 함. 
    코드의 주의사항을 달기보다는 코드를 다시 작성해라. 변수의 사용법을 설명하는 주석을 달기보다는 변수의 이름을 다시 지어라. 코드로 충분히 할 수있는 것을 주석으로 대체하지 말아라. 

    
 - 유용성을 유지하라
    주석은 당연한 것을 말하는 것이 아니라 당연하지 않다고 생각되는 의외의 것을 기록해야 한다. 주석으로 코드를 쉽게 설명할 생각은 하지 말고 그냥 코드를 쉽게 만들어라. 만약 더 이상 코드를 쉽고 명료하게 만들수가 없을 때에만 주석이 필요하다. 주석을 쓰레기 코드를 덮는 포장지로 사용해서는 안된다. 더이상 코드에 손댈게 없을때에야 진실되고 명료하고 알기 쉬운 주석을 달도록 노력해라. 


 - 주의를 흩트리지 마라
   코드가 주인이라는 사실을 잊지 말자. 따라서 주석을 달음으로서 불필요하게 코드 리딩과정에 주의를 흐트려서는 안된다. 쓸데 없는 아스키 기교로 주석의 네모 박스를 이쁘게 유지하는 등의 바보같은 노력을 하지 마라.
블록의 끝에  // end if ( a < 1 ) 같은 주석이 그럴듯 하게 보일지 모르지만 이 주석을 달 시간에 차라리 코드를 더 이쁘게 작성하고 지나친 중첩 block를 사용하지 말아라. 이런 주석은 코드가 수정될때 같이 수정이 되지 않아서 부패가 되고 썩어 버린다. 불필요한 코드만큼이나 불필요한 주석 그리고 공허한 주석을 달지 말아라.


주석에 대한 이런 관점은 주석은 필요악이라는 관점이다. - 비록 많은 사람들이 동의 하지 않을지라도 - More Comment, Better Code가 절대 아니다. 방법론에서 문서화들이 그러한 것처럼 Better Code를 추구하기 위한 과정일뿐 주석자체는 목적이 아니다. 그래서 좋은 코멘트를 작성하는 것보다는 좋은 코드를 작성하는것에 집중하는 것이 좋다.