Clean Code - 주석

주석

 

나쁜 코드에 주석을 달지 마라. 새로 짜라. – 브라이언 W. 커니핸, P.J. 플라우거

 

주석은 사실상 ‘필요악’이다. 프로그래밍을 통해 좋은 코드를 만들면 주석은 전혀 필요없다.

코드로 의도를 표현하지 못해서 실패를 만회하기 위해 주석을 사용하는 것이다.

 

주석이란

1.     주석은 나쁜 코드를 보완하지 못한다 : 코드 품질이 나쁘기 때문에 주석을 달아 알아먹기 쉽게 만들기 위해 주석을 단다. 틀렸다. 코드를 정리해서 좋은 코드를 만드는게 정답이다. 자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치워라.

2.     코드로 의도를 표현하라 : 개발자는 코드를 “의도를 표현하기 위한 훌륭한 수단” 이라고 생각해야 한다. 코드만으로 의도를 설명하기 어려운 것은 잘못된 생각이다. Ex) //직원에게 복지 혜택을 받을 자격이 있는지 검사한다. If(employee.flags && HOURLY_FLAG) 와 다음 코드 중 어떤 것이 더 깔끔한가? If(employee.isEligibleForFullBenefits())

3.     좋은 주석 : 어떤 주석은 필요하거나 유익하다. 그 목록은 다음과 같다.

1)    법적인 주석 : 법적인 이유로 특정 주석을 넣어야 할 때 필요하다.

2)    정보를 제공하는 주석 : 정규표현식과 같은 코드 위에 예제나 사용법을 주석으로 달아서 정보를 제공하는 주석은 도움이 된다.

3)    의도를 설명하는 주석 : 결정에 깔린 의도를 설명하는 주석은 때때로 유용하다.

4)    중요성을 강조하는 주석 : 대수롭지 않다고 여겨질 코드의 중요성을 강조할 때 유용하다.

4.     나쁜 주석 : 대다수 주석이 이 범주에 속한다.

1)    같은 이야기를 반복하는 주석 : 쓸모없고 중복된 주석이나 javadocs 는 가독성을 떨어뜨린다.

2)    오해할 여지가 있는 주석 : 살짝 잘못된 정보로 인해 함수를 잘못 사용하는 경우가 생긴다.

3)    의무적으로 다는 주석 : 모든 함수에 javadocs 를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다.

4)    이력을 기록하는 주석 : 소스 코드 관리 시스템이 있는 지금, 혼란만 가중시키는 주석일 뿐이다. 완전히 제거하는 편이 좋다.

5)    주석으로 처리한 코드 : 주석으로 처리한 코드는 다른 사람이 지우기를 주저한다. 남겨 놓으려고 주석으로 처리한 거라고 생각하기 때문이다. 쓸모 없는 주석이므로 주석으로 코드를 처리 하지 말아야 한다.