[클린코드 독서] 4장 - 주석

첫페이지부터 글쓴이는 강하게 이야기했다.

주석은 순수하게 선하지 못하다. 주석은 필요악이다.

이전에 자주 함수의 기능을 설명하기 위해 주석을 달곤했는데, 클린코드는 정말 많은 가르침을 주는거같다.

 

1. 주석은 필요악이다
   
   • 주석이 필요한 상황에 처하면 코드로 의도를 표현할 방법을 찾자
   • 주석은 나쁜 코드를 보완하지 못한다.
   • 주석으로 달려는 설명을 함수로 만들어 표현하자
2. 좋은 주석이란?
   • 법적
     • 저작권 정보나 소유권 정보
   • 정보 제공
     • 이것도 웬만하면 코드로 설명하기
     • 정규표현식이 무슨뜻인지 설명할때 정도는 사용해도되지만, 정규표현식을 사용하여 데이터를 처리하는 클래스를 만들어서 그쪽으로 코드를 옮긴다면 더 깔끔하다.

       • //kk:mm:ss EEE, MMM dd, yyyy 형식이다.
         Pateern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d, \\d");

   • 의도 설명
     • 코드를 이처럼 구현하게된, 결정에 깔린 의도를 설명하는 용도
     • 두 객체를 비교할때 왜 이 객체를 더 우선순위를 높게 매기도록 결정했는지 주석으로 써놓는경우
   • 의미를 명료하게 밝히는것
     • 일단은 모호한 인수나 반환값은 의미가 드러나게끔 코드로 표현하는게 더 좋지만
     • 만약 표준 라이브러리라서, 같은 경우로 변경을 못한다면 주석으로 의미를 명료하게 밝히자

     • assertTrue(a.compareTo(a) == 0 ); //a == a

   • 결과를 경고하는 것
     • 예를들어, 특정 테스트케이스는 웬만하면 돌리지 말아야할때, 경고하는것
       • 오래 걸린다든가, 서버에 부담이 좀 된다든가 등등
   • TODO
     • 앞으로 할일을 todo주석으로 남기는거
     • 이거 해봤는데 자바에서 있는거고, 이주석은 네온색이됨
   • 중요성을 강조하는 주석
     • 자칫 넘어갈만한 뭔가를 강조하기 위한거
     • 이 코드가 꼭 있어야 이게 된다던지 그런것
   • 공개API > Javadocs
3. 나쁜 주석이란?
   • 주절거리는것
   • 중복적인것
   • 오해할만한 것
   • 의무적으로 다는것
   • 이력을 기록하는것
   • 필요없는 것
   • 잡음
   • 함수나 변수로 표현가능하다면 달지말기
   • 닫는 괄호에 다는 주석
   • 저자를 표시하는 주석
   • 주석으로 처리한 코드
   • HTML 주석
   • 전역 정보
   • 너무 많은 정보
   • 모호한 관계
   • 함수 헤더
   • 비공개 코드의 Javadocs

 

정리하고 나니 나쁜주석에 대한 설명이 훨씬 많음을 알 수 있었다.

주석을 써야할때와 쓰지말아야할때를 정확하게 학습해서 사용해야겠다.