클린코드 4장 - 주석

나쁜 코드에 주석을 다지 마라. 새로 짜라

 

 

1. 주석은 나쁜 코드를 보완하지 못한다

표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.

자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라

 

2. 코드로 의도를 표현하라

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

//예제2.
if(employee.isEligibleForFullBenefits())

주석으로 달려는 설명을 함수로 만들어 표현해도 충분

 

3. 좋은 주석

- 법적인 주석(ex.저작권 정보, 소유권 정보...)

- 정보를 제공하는 주석

- 의도를 설명하는 주석

- 의미를 명료하게 밝히는 주석

- 결과를 경고하는 주석 : 요즘에는 @Ignore 속성을 이용해 테스트 케이스를 꺼버림

- TODO 주석(앞으로 할 일) : 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술

                                     요즘 나오는 대다수IDE는 TODO 주석을 전부 찾아 보여주는 기능을 제공함 

*IDE : 통합 개발 환경(Integrated Development Environment)

공통된 개발자 툴을 하나의 그래픽 사용자 인터페이스(Graphical User Interface, GUI)로 결합하는 애플리케이션을 구축하기 위한 소프트웨어 ex) Visual Studio, 이클립스...

- 중요성을 강조하는 주석

 

4. 나쁜 주석

- 주절거리는 주석

- 같은 이야기를 중복하는 주석 : 코드보다 주석을 읽는 시간이 더 오래 걸릴수도 있음

- 오해할 여지가 있는 주석

- 의무적으로 다는 주석 : 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석음

*Javadocs : http://ojc.asia/bbs/board.php?bo_table=LecJava&wr_id=278

- 이력을 기록하는 주석

- 있으나 마나 한 주석 : 너무나 당연한 사실을 언급하는 주석

- 함수나 변수로 표현 할 수 있다면 주석을 달지 마라

- 위치를 표시하는 주석 : ex. // Actions /////////////////////////////////////////

                                 이런 주석은 유용한 경우도 있지만 가독성만 낮추므로 반드시 필요한 겨우에만 사용

- 닫는 괄호에 다는 주석

- 공로를 돌리거나 저자를 표시하는 주석 :ex. /*릭이 추가함*/   

- 주석으로 처리한 코드 : 주석으로 처리된 코드는 사람들이 이유가 있어 남겨 놓았으리라고, 중요하니까 지우면 안된다    고 생각함

- HTML 주석 : 혐오 그 자체랴

- 전역 정보 : 주석을 달아야 한다면 근처에 있는 코드만 기술, 시스템의 전반적인 정보를 기술하지 말것

- 너무 많은 정보 : 주석에다 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓지 마라

- 모호한 관계 : 주석자체가 다시 설명을 요구하게 되면 안됨

- 함수 헤더 : 이름을 잘 붙인 헤더가 주석보다 좋음

- 비공개 코드에서 Javadocs : 공개 API는 Javadocs가 유용하지만 공개하지 않을 콛드라면 쓸모 x