[Clean Code] 4장 주석

 

깨끗한 코드를 작성하기 위한 네번째 기록

 

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

우리는 코드로 의도를 표현하지 못해, 실패를 만회하기 위해 주석을 사용한다. 여기서 내가 실패라는 단어를 썼다는 사실에 주목한다. 주석은 언제나 실패를 의미한다. 때때로 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다. 주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다. 상황을 역전해 코드로 의도를 표현할 방법은 없을까?

 

코드로 의도를 표현하라

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if((employy.flags & HOURLY_FLAG) &&
	(employy.age > 65))

if(employee.isEligibleForFullBenefits())

두 가지 코드를 보면 주석을 사용하지 않고, 코드로 의도를 표현하는 방법을 알 수 있다.

 

좋은 주석

정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이다.

1. 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하고도 타당하다.
2. 기본적인 정보를 주석으로 제공한다. 예를 들어 추상 메서드가 반환할 값을 설명한다.
3. 의도를 설명하는 주석
4. 의미를 명확하게 밝히는 주석
5. 결과를 경고하는 주석
6. 중요성을 강조하는 주석
7. TODO 주석
8. 공개 API에서 Javadocs

 

나쁜 주석

1. 주절거리는 주석
2. 같은 이야기를 반복하는 주석 - 함수를 설명
3. 코드 만으로 이해되는 내용을 주석으로 설명
4. HTML 주석
5. 코드를 주석으로 없앤 것

 

마무리

코드를 짤 때 협업하는 팀원이 코드를 이해할 수 있게 주석을 항상 달았습니다.
이 법칙을 알게되니 저는 좋은 코드를 짜는 것을 실패했던 것이었습니다.

앞으로는 클린 코드를 짜서 나쁜 주석을 쓰지 않고 꼭 필요한 좋은 주석만을 사용하겠습니다.
실무에서 이 법칙을 꼭 기억하고 녹여내도록 노력하겠습니다.

 

[출처]
Clean Code (클린 코드,애자일 소프트웨어 장인 정신), 로버트 C. 마틴 저