4장 주석

주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다. 상황을 역전해 코드로 의도를 표현할 방법은 없을까?

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

코드가 엉망진창이라 설명하기 위해서 주석을 단다? 그냥 코드를 깔끔하게 바꿔라.

뼈때리네..

코드로 의도를 표현하라

//직원이 복지해택 받을 자격 있으면...
if (employee.flag==True){
...
}

이렇게 하지말고

if (employee.isEligibleForFullBenefits()){
...
}

이렇게 하자

좋은 주석

아래는 글자값 하는 주석의 목록이다.

• 법적인 주석: 코드 파일 첫머리의 저작권 정보 등..
• 정보를 제공하는 주석: //YYMMDD 형식이다. 등
• 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석: 인수나 반환값 변수를 바꿀 수 없는 경우..
• 결과를 경고하는 주석
• TODO 주석
• 중요성을 강조하는 주석

나쁜 주석

아래는 나쁜 주석의 목록이다.

• 주절거리는 주석
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석 : 얘는 무슨변수..쟤는 무슨변수..
• 이력을 기록하는 주석: //이 함수는 어디로 옮겼음..
• 있으나마다 한 주석: //기본 생성자..(이정도 설명은 지나친 참견임)
• 무서운 잡음 : 무지성 주석 복붙은 실수를 부릅니다.
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 위치를 표시하는 주석
• 닫는 괄호에 다는 주석
• 공로를 돌리거나 저자를 표시하는 주석
• 주석으로 처리한 코드 : 걍 지우자
• HTML 주석
• 전역 정보 : 주석을 달아야 한다면 근처의 코드만 설명
• 너무 많은 정보: 쓸데없는 정보 적지 말기
• 모호한 관계: 주석 자체가 다시 설명을 요구하면 안되겠지
• 함수 헤더: 이름 잘 붙이면 함수에 주석붙일 이유 없음
• 비공개 코드에서 Javadocs