Chapter 4. 주석
나쁜 코드에 주석을 달지 마라. 새로 짜라.
잘 달린 주석은 그 어떤 정보보다 유용하다. 하지만 경솔하고 근거없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다. 사실 주석은 기껏해야 필요악이다. 우리는 코드로 의도를 표현하지 못해, 실패를 만회하기 위해 주석을 사용한다. 주석은 언제나 실패를 의미한다.
상황을 역전해 코드로 의도를 표현할 방법은 없을까?
"코드로 의도를 표현할 때마다 스스로를 칭찬해 준다. 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 한다.
주석을 무시하는 이유는 '거짓말'을 해서 이다. 오래된 코드일 수록 주석과는 더욱 멀어진다. 오래될수록 완전히 그릇될 가능성도 커진다. 코드는 변화하고 진화한다. 또 프로그래머들이 주석을 유지보수하기란 현실적으로 불가능하기에 그렇다.
또 부정확한 주석은 아에 없는 주석보다 더 나쁘다. 독자를 현혹하고 오도하기 때문이다. 부정확한 주석은 결코 이뤄지지않을 기대를 심어준다. 더 이상 지킬 필요가 없는 규칙이나 지켜서는 안되는 규칙을 명시한다.
주석은 나쁜 코드를 보완하지 못한다.
코드에 주석을 추가하는 일반적인 이유는 코드의 품질이 나쁘기 때문이다. 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
하지만 확실히 코드만으로 의도를 설명하기 어려운 경우가 존재한다. 불행히도, 많은 개발자가 코드는 훌륭한 수단이 아니라는 의미로 해석한다. 하지만, 분명히 잘못된 생각이다. 다음 코드예제 두개를 본다면 어느 쪽이 더 나을까 ?
//직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if{(employee.flags & HOURLY_FLAG) && (employee.age > 65)}다음 코드는
if(employee.isEligbleForFullBenefits())1. 좋은 주석
어떤 주석은 필요하거나 유익하다. 지금부터 글자값을 한다고 생각하는 주석 몇가지롤 보여주겠다. 하지만, 정말 좋은 주석은 주석을 달지 않을 방법을 찾아낸 주석 이라는 사실이다.
- 법적인 주석
- 정보를 제공하는 주석
- 의도를 설명하는 주석
- 의미를 명료하게 밝히는 주석
- 결과를 경고하는 주석
- TODO주석
- 중요성을 강조하는 주석
- 공개 API에서 Javadocs
2. 나쁜 주석
대다수 주석이 이 범주에 속한다. 대다수 주석은 허술한 코드를 지탱하거나, 엉성한 코드를 변명하거나 미숙한 결정을 합리화 하는등 프로그래머가 주절거리는 독백에서 크게 벗어나지 못한다.
- 주절거리는 주석
- 같은 이야기를 중복하는 주석
- 오해할 여지가 있는 주석
- 의무적으로 다는 주석
- 이력을 기록하는 주석
- 있으나 마나 한 주석
- 무서운 잡음
- 위치를 표시하는 주석
- 닫는 괄호에 다는 주석
- 공로를 돌리거나 저자를 표시하는 주석
- 주석으로 처리한 코드들..
- HTML 주석
- 전역정보와 너무많은 정보
- 모호한 관계
- 비공개 코드에서의 Javadocs
느낀점
이번 단원에서는 다른 단원과는 다르게 클린코드 책에서 명시된 '결론'이 없어서 느낀점만 명시한다. 평소 많은 주석을 사용한 나로써는 정말 흥미있게 읽어본 파트였던것 같다. 그리고 앞으로 리팩토링을 하게될 모든 프로젝트에 주석을 잘 사용할것이라 생각하던 찰나였다. 하지만 이것이 웬일인가?
책에서는 주석사용을 최대한 지양하라 이야기한다. 그리고 정말 않좋은 주석은 충분히 혼란을 준다.... 나도 이미 몇번 경험해본 기억이 난다.. 정말 그것때문에 , 그 한줄때문에 여러사람이 3시간동안 머리싸메고 헤메던 기억이 난다...
이번 단원에 예시코드 위주로 적어 구성해볼까 생각도 하였지만, 적기엔 양이 너무 방대하단 생각이들어 고민이 많았다.. 일단 , 가볍게 정독을 한것을 만족하고 추후 보완을 하는 방향으로 가야겠단 생각이든다. 다른사람의 TiL을 읽어봐야겠다. 그리고 명시해 놓을 생각이다.
