주석은 나쁜 코드를 보완하지 못함
표현력 풍부, 깔끔, 주석 거의 없는 코드 >>>>> 복잡, 어수선, 주석 많이 달린 코드
코드로 의도 표현하기
코드만으로 의도 설명하기 어려운 경우 존재함 != 코드는 훌륭한 수단이 아님
//직원에게 복지 혜택 받을 자격 있는지 검사
if((employee.flags & HOURLY_FLAG) && (employee.age>65)
if(employee.isEligibleForFullBenefits())주석으로 달려는 설명을 함수로 만들어 표현하기
좋은 주석
- 법적인 주석
- ex) 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보, 소유권 정보는 필요함
- 모든 조항, 조건 열거하는 대신 표준 라이센스나 외부 문서 참조해도 됨
- 정보 제공하는 주석
- 때로는 기본적인 정보를 주석으로 제공하면 편함
//kk:mm:ss EEE, MMM dd, yyyy 형식
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w \\d*, \\d*");
//-> 이왕이면 시각, 날짜 변환하는 클래스 만들어 코드 옮기면 더 깔끔해지고 주석 필요 없어짐- 의도 설명하는 주석
- 결정에 깔린 의도까지 설명할 때 있음
- ex) //오른쪽 유형이므로 정렬 순위 더 높음
//스레드 대량 생성하는 방법으로 어떻게든 경쟁 조건 만들려 시도함
- 의미 명료하게 밝히는 주석
- 모호한 인수, 반환값은 그 의미 읽기 좋게 표현하면 이해하기 쉬워짐
- 인수나 반환값이 표준 라이브러리 or 변경 못하는 코드에 속하면 주석이 유용해짐
- 더 나은 방법 고민, 정확히 달도록 주의해야 함
- 결과 경고하는 주석
- 다른 프로그래머에게 결과 경고할 목적으로 주석 사용함
- 요즘에는 @Ignore 속성 이용해 test case 꺼버림
@Ignore("실행이 너무 오래 걸린다.")
- TODO 주석
- 앞으로 할 일을 //TODO 주석으로 남겨두기
- //TODO-MdM 현재 필요하지 않음
//체크아웃 모델 도입하면 함수 필요없음 - 더 이상 필요없는 기능 삭제하라는 알림, 문제 봐달라는 요청, 좋은 이름 떠올려달라는 부탁, 발생할 이벤트에 맞춰 코드 고치라는 주의 등에 유용함
- 주기적으로 TODO 주석을 없앨 것
- 중요성 강조하는 주석
- 중요성 강조하기 위해 주석 사용함
- 공개 API에서 Javadocs
나쁜 주석
- 주절거리는 주석
- 주석을 달기로 결정했다면 충분한 시간을 들여서 최고의 주석 달도록 노력할 것
- 이해가 안돼서 다른 모듈까지 뒤져야 하는 주석 == 독자와 소통하지 못하는 주석 (바이트만 낭비함)
- 같은 이야기 중복하는 주석
- 주석이 코드보다 더 많은 정보 제공하지 못함, 코드 정당화하지 않음, 의도/근거 설명하는 주석도 아님
/**
* 컨테이너와 관련된 Loader 구현
*/
protected Loader loader = null- 오해할 여지가 있는 주석
- ex) //this.closed가 true로 변할 때 메서드 반환됨
this.closed가 true여야 메서드 반환됨
아니면 무조건 타임아웃 기다렸다가 그래도 this.closed가 true 아니면 예외 던짐
this.closed가 true로 변하는 순간에 함수 반환된다고 생각할 수도 있음
- ex) //this.closed가 true로 변할 때 메서드 반환됨
- 의무적으로 다는 주석
- 모든 함수에 javadocs를 달거나 변수에 주석을 달아야 한다는 규칙 등
- 이력 기록하는 주석
- 소스 코드 관리 시스템 없을 때 모든 모듈 첫머리에 변경 이력 기록, 관리하는 관례 있었음
- 지금은 완전 제거하는 편이 좋음
- 있으나 마나 한 주석
- 너무 당연한 사실 언급하며 새로운 정보 주지 못함
/**
* 기본 생성자
*/
protected AnnualDateRule(){
}- 무서운 잡음
/** The name. */
private String name;- 함수나 변수로 표현 가능하다면 주석 달지 말 것
- 주석 필요하지 않도록 코드 개선하는 것이 좋음
- 위치 표시하는 주석
- // Actions //////////////////////
- 극히 드물지만 이런 배너 아래 특정 기능 모아놓으면 유용할 수도 있음
- 일반적으로 가독성 낮춤 (뒤의 /들 지우기) - 반드시 필요할 때만, 드물게 사용할 것
- 닫는 괄호에 다는 주석
- 닫는 괄호에 주석 달고 싶다면 함수 줄이기 시도하기
- 공로 돌리거나 저자 표시하는 주석
- 소스 코드 관리 시스템에 저장하는 것이 좋음
- 주석으로 처리한 코드
- 정리하기
- HTML 주석
- 전역 정보
- 코드 일부에 주석 달면서 시스템 전반적인 정보 기술하지 말기
- 너무 많은 정보
- 흥미로운 역사, 관련 없는 정보 적지 않기
- 모호한 관계
- 주석과 코드는 둘 사이 관계가 명백해야 함
- 함수 헤더
- 짧은 함수는 긴 설명이 필요 없음
- 비공개 코드에서 Javadocs
주석은 나쁜 코드를 보완하지 못함
표현력 풍부, 깔끔, 주석 거의 없는 코드 >>>>> 복잡, 어수선, 주석 많이 달린 코드
코드로 의도 표현하기
코드만으로 의도 설명하기 어려운 경우 존재함 != 코드는 훌륭한 수단이 아님
//직원에게 복지 혜택 받을 자격 있는지 검사 if((employee.flags & HOURLY_FLAG) && (employee.age>65) if(employee.isEligibleForFullBenefits())
주석으로 달려는 설명을 함수로 만들어 표현하기
좋은 주석
- 법적인 주석
- ex) 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보, 소유권 정보는 필요함
- 모든 조항, 조건 열거하는 대신 표준 라이센스나 외부 문서 참조해도 됨
- 정보 제공하는 주석
- 때로는 기본적인 정보를 주석으로 제공하면 편함
//kk:mm:ss EEE, MMM dd, yyyy 형식 Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w \\d*, \\d*"); //-> 이왕이면 시각, 날짜 변환하는 클래스 만들어 코드 옮기면 더 깔끔해지고 주석 필요 없어짐
- 의도 설명하는 주석
- 결정에 깔린 의도까지 설명할 때 있음
- ex) //오른쪽 유형이므로 정렬 순위 더 높음
//스레드 대량 생성하는 방법으로 어떻게든 경쟁 조건 만들려 시도함
- 의미 명료하게 밝히는 주석
- 모호한 인수, 반환값은 그 의미 읽기 좋게 표현하면 이해하기 쉬워짐
- 인수나 반환값이 표준 라이브러리 or 변경 못하는 코드에 속하면 주석이 유용해짐
- 더 나은 방법 고민, 정확히 달도록 주의해야 함
- 결과 경고하는 주석
- 다른 프로그래머에게 결과 경고할 목적으로 주석 사용함
- 요즘에는 @Ignore 속성 이용해 test case 꺼버림
@Ignore("실행이 너무 오래 걸린다.")
- TODO 주석
- 앞으로 할 일을 //TODO 주석으로 남겨두기
- //TODO-MdM 현재 필요하지 않음
//체크아웃 모델 도입하면 함수 필요없음 - 더 이상 필요없는 기능 삭제하라는 알림, 문제 봐달라는 요청, 좋은 이름 떠올려달라는 부탁, 발생할 이벤트에 맞춰 코드 고치라는 주의 등에 유용함
- 주기적으로 TODO 주석을 없앨 것
- 중요성 강조하는 주석
- 중요성 강조하기 위해 주석 사용함
- 공개 API에서 Javadocs
나쁜 주석
- 주절거리는 주석
- 주석을 달기로 결정했다면 충분한 시간을 들여서 최고의 주석 달도록 노력할 것
- 이해가 안돼서 다른 모듈까지 뒤져야 하는 주석 == 독자와 소통하지 못하는 주석 (바이트만 낭비함)
- 같은 이야기 중복하는 주석
- 주석이 코드보다 더 많은 정보 제공하지 못함, 코드 정당화하지 않음, 의도/근거 설명하는 주석도 아님
/** * 컨테이너와 관련된 Loader 구현 */ protected Loader loader = null
- 오해할 여지가 있는 주석
- ex) //this.closed가 true로 변할 때 메서드 반환됨
this.closed가 true여야 메서드 반환됨
아니면 무조건 타임아웃 기다렸다가 그래도 this.closed가 true 아니면 예외 던짐
this.closed가 true로 변하는 순간에 함수 반환된다고 생각할 수도 있음
- ex) //this.closed가 true로 변할 때 메서드 반환됨
- 의무적으로 다는 주석
- 모든 함수에 javadocs를 달거나 변수에 주석을 달아야 한다는 규칙 등
- 이력 기록하는 주석
- 소스 코드 관리 시스템 없을 때 모든 모듈 첫머리에 변경 이력 기록, 관리하는 관례 있었음
- 지금은 완전 제거하는 편이 좋음
- 있으나 마나 한 주석
- 너무 당연한 사실 언급하며 새로운 정보 주지 못함
/** * 기본 생성자 */ protected AnnualDateRule(){ }
- 무서운 잡음
/** The name. */ private String name;
- 함수나 변수로 표현 가능하다면 주석 달지 말 것
- 주석 필요하지 않도록 코드 개선하는 것이 좋음
- 위치 표시하는 주석
- // Actions //////////////////////
- 극히 드물지만 이런 배너 아래 특정 기능 모아놓으면 유용할 수도 있음
- 일반적으로 가독성 낮춤 (뒤의 /들 지우기) - 반드시 필요할 때만, 드물게 사용할 것
- 닫는 괄호에 다는 주석
- 닫는 괄호에 주석 달고 싶다면 함수 줄이기 시도하기
- 공로 돌리거나 저자 표시하는 주석
- 소스 코드 관리 시스템에 저장하는 것이 좋음
- 주석으로 처리한 코드
- 정리하기
- HTML 주석
- 전역 정보
- 코드 일부에 주석 달면서 시스템 전반적인 정보 기술하지 말기
- 너무 많은 정보
- 흥미로운 역사, 관련 없는 정보 적지 않기
- 모호한 관계
- 주석과 코드는 둘 사이 관계가 명백해야 함
- 함수 헤더
- 짧은 함수는 긴 설명이 필요 없음
- 비공개 코드에서 Javadocs
