1. 주석을 최대한 쓰지 말자
// 직원에게 복지 혜택을 받을 자격이 있는지 검사
if ((employee.flags & HOURLY_FLAG) && employee.age > 65))
// 의미있는 이름을 지으면 해결됨
if (employee.isEligibleForFullBenefits())
Java
복사
주석은 나쁜 코드를 보완하지 못한다
•
코드에 주석을 추가하는 이유는 코드 품질이 나쁘기 때문이다. 자신이 저지른 난장판을 주석으로 설명하지 말고 개선하는데 시간을 보내야 한다.
•
코드로도 의도를 표현할 수 있다.
주석은 방치된다
•
코드의 변화에 따라가지 못한 채 주석은 방치된다.
•
코드는 컴파일되어 호출되나 주석은 그저 주석이다. 그 자리에 방치되고 결국 의미없는 텍스트가 된다.
2. 좋은 주석
1.
좋은 주석은 구현에 대한 정보를 제공한다
// kk:mm:ss EEE, MMM dd, yyyy 형식
Pattern timeForamt = Pattern.compile("\\d*:\\d:\\d* \\w*, \\w* \\d* \\d*");
Java
복사
2.
좋은 주석은 의도와 중요성을 설명해준다
// 스레드를 많이 생성하여 시스템에 영향을 끼쳐 테스트를 만들도록 함
for (int i = 0; i < 25000; i++) {
SomeThread someThread = ThreadBuilder.builder().build();
}
Java
복사
// 유저로부터 입력받을 값을 저장할 때 trim으로 공백제거 필요
String userName = userNameInput.trim();
Java
복사
3.
// TODO // FIXME
•
TODO : 앞으로 할 일. 지금은 해결하지 않지만 나중에 해야할 일을 미리 적어둘 때
•
FIXME : 문제가 있지만, 당장 수정할 필요는 없을 때. 가능하면 빨리 수정하는 게 좋음
⇒ IDE에서 하이라이팅되며, 별도의 윈도우에서 볼 수 있음
3. 주석보다 annotation
java.lang.annotation
•
annotation : 코드에 대한 메타 데이터
◦
코드의 실행 흐름에 간섭을 주기도 하고, 주석처럼 코드에 대한 정보를 주기도 한다.
•
@Deprecated : 컴파일러가 warning을 발생시킴. IDE에서 사용 시 표시가 된다.
•
@NotThreadSafe : Thread Safe 하지 않음을 나타낸다.
4. JavaDoc
Java 코드에서 API 문서를 HTML 형식으로 생성해주는 도구
•
Class level
•
Field level
•
Method level
•
JavaDoc 문서
5. 이번 파트 정리
지나친 주석은 코드 해석에 오히려 부담을 주거나 혼란을 야기할 수 있다. 주석이 나쁜 코드를 보완하지 못하거나 방치된다는 이유에서 주석을 남발한다면 주석을 사용하는 의미가 없어진다. 하지만 상황에 따라 주석을 작성해야 하는 경우가 분명히 발생한다. 코드를 통해 개발자의 의도를 100% 표현할 수 있는 것도 아닐 뿐더러 오히려 주석을 통해 코드의 기능과 중요성을 명확하게 정리함으로써 코드를 이해하는 데 도움이 되는 사례도 있다. 만약에 레거시 코드를 활용하여 뭔가 작업을 해야 하는데 제대로 정리되지 않은 레거시 코드여서 일일이 기능 분석을 한 다음 누군가에게 전달을 해야 한다면 메소드명을 수정하는 것보다 주석으로 설명을 다는 게 더 적합할 수 있다. 결론적으로 적재적소에 주석을 활용하는 것이 개발자의 현명한 대처가 아닐까 싶다.