주석은 거짓말을 한다. 프로그램이 변하고 진화함에 따라 프로그래머가 주석을 매번 유지. 보수하기는 불가능하다. 따라서 시간이 지날수록 주석은 거짓말을 하게 되고, 쓸모없어지고, 있으면 안되는 존재가 된다.
주석은 잘 작성된 코드로 대체할 수 있다. 코드로 모든 것을 표현하도록 연습해야 한다.
좋은 주석
1. 법적인 주석
법적인 정보, 예를 들어 저작권이나 소유권을 나타내는 정보는 글 머리에 주석으로 작성한다.
2. 정보를 제공하는 주석
기본적인 정보를 주석으로 제공하면 편리하다.
하지만 클래스를 이용하거나 함수, 변수명으로 정보를 제공하도록 노력해야 한다.
도저히 방법이 없다면 주석으로 정보를 제공한다.
3. 의도를 설명하는 주석
예를 들어, 에라토스테네스의 채 알고리즘을 구현할 때, 시간복잡도를 줄이기 위해 루트 n까지의 반복을 수행한다.
코드상에서 왜 N이 아닌 루트N 까지 반복을 하였는지에 대한 의도를 주석으로 설명할 수 있다.
4. 의미를 명료하게 밝히는 주석
인수나 반환값에 원시값이 들어가거나 해서 의미가 모호해지는 경우가 있다.
물론 매직넘버를 피하기 위해 상수를 정의해서 쓰는 것이 더 좋은 방법이지만,
라이브러리나 정책상 이를 변경할 수 없다면 의미를 밝히는 주석을 다는 방법이 좋을 수 있다.
5. 결과를 경고하는 주석
SimpleDateFormat 객체는 스레드에 안전하지 못하다. 따라서 인스턴스를 독립적으로 생성해야 한다는 주석을 남길 수 있다.
또는 어떤 메소드가 실행되는 시간이 엄청 길다고 치자. 그럼 실행 시간이 길다는 경고를 날릴 수 있다.
6. TODO 주석
앞으로의 할 일을 TODO 주석으로 남기면 편하다.
// TODO 이후에 할 일을 적어 놓는다. (인텔리제이에서는 다른 주석과 색이 다르다.)
구현해야 하지만, 당장은 구현하기 힘든 것들을 적어 놓는다.
7. 중요성을 강조하는 주석
대수롭지 않게 여겨서 후에 문제가 생길법한 코드에 주석을 달아 강조할 수 있다.
8. 공개 API에서 Javadocs
표준 자바 라이브러리의 Javadocs처럼 공개 API를 구현할 때, Javadocs 주석으로 문서를 만들 수 있다.
나쁜 주석
1. 주절거리는 주석
특별한 이유 없이 의무감으로, 혹은 어떤 의무로 주석을 다는 것은 나쁜 주석이다.
주석조차 이해가 되지 않아 다른 모듈을 뒤져야 한다면 주절거리는 것 이상이 아니다.
2. 같은 이야기를 중복하는 주석
주석이 코드보다 더 많은 정보를 제공하지 못한다면 중복된 정보이다.
주석이든 Javadocs든 중복된 주석은 나쁘다.
3. 오해할 여지가 있는 주석
4. 의무적으로 다는 주석
의무감으로 모든 함수에 Javadocs를 달거나 변수에 주석을 다는 것은 나쁘다.
코드가 복잡해지고, 거짓말이 늘어나고, 잘못된 정보를 제공할 여지만 늘어나게 된다.
5. 이력을 기록하는 주석
git 같은 소스 코드 관리 시스템에서 하자.
6. 있으나 마나 한 주석
생성자 위에 //생성자 는 정말 없느니 못하다.
있으나 마나한 주석을 계속 보다보면 주석을 당연하게 여겨 무시하는 습관에 빠질 수 있다.
코드를 읽지 않는다면 중요 정보를 놓칠 수 있다.
결국은 코드가 바뀌면 주석은 거짓말로 변하게 된다.
예를 들어 try / catch 문 안에 오류를 잡고 아무일도 하지 않는다면 그에대한 설명을 적는 주석은 타당하다.
try {
doSomething();
} catch(Exception e) {
// 정상. 동작을 멈추는 명령이 들어옴.
}
하지만 아래처럼 그냥 남겨놓는 주석은 있으나 마나이다.
try {
doSomething();
} catch(Exception e) {
// 오류
}
7. 함수나 변수로 표현할 수 있다면 주석을 달지 마라.
// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (smodule.getdependSubsystem().contains(subSysMod.getSubSystem()))이 코드는 아래의 코드로 바꿀 수 있다.
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))코드와 변수명으로 표현하는 방법으로 바꾸는 연습이 필요하다.
8. 위치를 표시하는 주석
복잡한 코드에서 위치를 한눈에 볼 수 있는 주석이 극히 적은 경우로 편리할 수 있긴 하다.
하지만 복잡한 코드부터 고치면 이 주석 또한 필요없다.
9. 닫는 괄호에 다는 주석
위와 같은 상황으로 복잡한 코드에서 닫는 괄호가 중첩되어 있는 경우 닫는 괄호에도 주석이 편리할 수 있긴 하다.
하지만 복잡한 코드부터 고치면 이 주석 또한 필요없다.
10. 공로를 돌리거나 저자를 표시하는 주석
누군가가 작성한 코드다 라는 것을 알리는 주석은 필요없다.
작성일 기록과 마찬가지로 코드 관리 시스템에 다 저장할 수 있다.
11. 주석으로 처리한 코드
주석으로 처리한 코드는 협업자가 봤을때 삭제하면 안될 이유가 있어서 주석처리했다 라고 생각이 든다.
따라서 이 코드는 가면 갈수록 쌓이고 의미없는 코드가 된다.
삭제하면 안될 이유가 있어서 주석을 달 것이라 해도 소스 코드 관리 시스템에서 다 기억해주므로 그냥 삭제하라.
12. HTML 주석
HTML 주석은 혐오 그 자체다.
Javadocs 같은 도구로 문서를 웹으로 올리는 경우에도 주석에 HTML코드를 작성하는 것은 프로그래머의 책임이 아니라
도구의 책임이다.
13. 전역 정보
주석은 주석의 내용이 실행되는 곳 근처에 작성되어야 한다.
하나의 메소드에 메소드에 대한 주석과 전역에 적용되는 주석을 써놓는다면, 나쁜 주석이다.
코드가 변하고 주석과 코드의 거리가 멀어짐에 따라 코드가 변경됬을때 주석이 변경되지 않을 확률이 올라간다.
14. 너무 많은 정보
쓸데없는 정보(흥미로운 역사..) 적지마라.
15. 모호한 관계
주석과 코드는 확실한 관계를 맺고 주석을 보면 코드가 이해가야 한다.
주석을 보고 코드를 봤는데 주석의 내용이 코드의 어느부분에 적용되는 설명인지 모른다면, 나쁜 주석이다.
16. 함수 헤더
짧고 간결한 함수는 주석이 필요 없다.
함수의 헤더에 주석으로 말끔히 설명한 코드보다 짧은 함수로 명확히 의미전달하는 함수가 더 좋다.
17. 비공개 코드에서 Javadocs
비공개 코드에서의 Javadocs 문서작성은 의미가 없다.