Chapter 4 - Comments
in Booknotes / Clean Code
나쁜 코드에 주석을 달지 마라. 새로 짜라.
주석은 나쁜 코드를 보완하지 못한다
- 주석은 기껏해야 필요악, 필수가 아니다. (\(\Rightarrow\) 시패)
- 우리의 의도대로 코드를 표현하지 못해 (실패를 만회하기 위해) 사용
- 오래될수록 코드와 멀어져 고아가 된다
- 개발자들은 주석을 유지보수 하지 않는다.
- 리팩토링/여기저기 옮겨지면서 주석은 따라가지 못하는 경우가 부지기수
- 진실은 오직 코드에만 존재한다. 부정확한 주석은 현혹하고 오도할 뿐
- 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가 좋다. 난장판을 설명하지 말고 치워라.
코드로 의도를 표현하라!
코드만으로 의드를 설명하기 어려운 경우에도 주석으로 해결하려는 대신 조금만 더 생각해보기
// 직원의 복지혜택 자격 확인
if( ( employee.flags & HOURLY_FLAG ) && ( employee.age > 65 ) )
vs
if( employee.isEligibleForFullBenefits() )
좋은 주석
- 주석을 달지 않을 방법을 찾아낸 주석이 가장 좋다
- 법적인 주석: License (copyright)등
요즘은 IDE에서 코드로 표기해주긴 함 - 정보 제공: 반환값 (이름을 바꾸면 더 굳) or 정규표현 예시
- 의도 설명
결정에 깔린 의도까지 설명 - 의미를 명료하게 밝힘
이름 변경 불가한 라이브러리같은 경우 단, 검증할 방법이 없으니 더욱 신경써서 달기 - 결과를 경고:
오래 걸리기 때문에 해당 테케는 여유로울때 하기 등등 - TODO:
//TODO, 떡칠금지 - 중요성을 강조
- 공개 API에서의 Javadocs
나쁜 주석
- 대다수 주석 is classified here
- 개발자의 독백으로 끝나는 경우가 많음
- 주절거리는 주석: 소통 불가, 결국엔 코드를 뜯어봐야 함
- 같은 이야기를 중복: 코드보다 읽거나 이해하는데 오래걸리는
- 오해의 여지
- 의무적인 주석: 모든 함수마다 javadcos 필요 X
- 변경이력 기록
- 있으나마나 한 주석: (너무나 당연해서) 개발자가 주석을 무시하는 습관이 생김
- 무서운 잡음 : javadocs 도 이렇게 될 수 있다
- 함수나 변수로 표현할 수 있다면 주석을 달지 않기
- 위치 표시 : 배너처럼 사용
/////////////////////////////, 쓸모 있을 때도 있지만 최대한 지양 - 닫는 괄호에 다는 주석: 차라리 함수를 줄이기
- 공로, 저자 표시: 소스관리 시스템이 해줌
- 주석으로 처리한 코드 : 나중에 지우기를 주저함 \(\rightarrow\) 코드가 쌓임. 마찬가리조 소스관리가 해줌
- HTML (이나 JSX)를 주석처리한 것
- 전역 정보: 근처에 있는 코드만 기술하기. 전체 default값 같은 건 기록X (유지보수 안될 가능성 높음)
- 너무 많은 정보
- 모호한 관계: 명확한 명사 동사 사용
- 함수 헤더: 차라리 이름으로 표기
- 비공개 코드에서 Javadocs
