잘 달린 주석은 어떤 정보보다도 유용하다.
하지만 잘 짜여진 코드가 있다면 굳이 주석을 달 필요는 없다. 주석은 또다른 위험성을 동반하기 때문이다.
많은 프로그래머들이 코드를 관리하는 것도 벅차기에 주석을 같이 엄격하게 관리하기는 힘들다. 과거의 주석이 현재의 코드에 혼란을 주는 사례들이 왕왕 있다.
그렇기에 코드로 의도를 표현하는 것이 주석을 쓰는것보다 좋다.
하지만 어떤 주석은 필요하거나 유익하다. 그런 주석들을 해당 장에서는 소개하고 있다.
좋은 주석
법적인 주석
- 소스코드 첫머리에 추가하는 저작권 등의 법률을 알리는 주석
정보를 제공하는 주석
- 정보를 제공하는 주석은 코드에 의미를 잘 담는다면 달지 않는 것을 지향한다.
의도를 설명하는 주석
public int compareTo(Object o) {
if (o instanceof WikiPagePath) {
WikiPagePath p = (WikiPagePath) 0;
String compressedName = StringUtil.join(names, "");
String compressedArgumentName = StringUtil.join(p.names, "");
return compressedName.compareTo(compressedArgumentName);
}
return 1; // 오른쪽 유형이므로 정렬 순위가 더 높다.
}의미를 명료하게 밝히는 주석
assertTrue(a.compareTo(a)=0); //a == a
assertTrue(a.compareTo(b) != 0); // a != b단, 그릇된 주석을 달 확률이 높기 때문에 더 나은 방법이 없는지 고민할 것.
결과를 경고하는 주석
특정 테스트 케이스를 꺼야하는 이유(테스트 시간이 오래걸린다거나 메모리를 많이 잡아먹는다거나 하는 이유)를 설명하는 주석
TODO 주석
필요하다 여기지만 당장 구현하기 어려운 업무를 기술. → 주기적으로 점검해 없애도 괜찮은 주석은 없앨것.
중요성을 강조하는 주석
자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하는 역할
나쁜 주석
주석을 달았으나 이해가 안되어 다른 모듈까지 뒤져야 하는 주석은 없는게 낫다.
같은 이야기를 중복하는 주석
명료한 코드에 충분한 의미가 담겼다면 해당 주석은 필요 없다. 코드에 의미가 담겼는데 주석을 다는 것도 같은 이야기를 중복하는 것에 속한다.
오해할 여지가 있는 주석
의무적으로 다는 주석
javadocs의 모든 변수에 주석을 달아야 하는 규칙등이 해당 규칙에 해당할 수 있음.
이력을 기록하는 주석
모듈을 편집할때마다 주석에 변경을 기록하는 것을 지양하자. 여러 코드 관리 도구의 등장으로 이젠 없어도 된다.
있으나 마나한 주석
너무 당연한 사실을 언급하여 새로운 정보를 제공하지 못하는 주석
위치를 표시하는 주석
// Actions /////////////////////////////이러한 배너 아래에 특정 기능을 모아두면 유용한 경우도 있긴 함. 하지만 일반적으로 가독성을 해치므로 드물게 사용할 것.
닫는 괄호에 다는 주석.
3장의 함수는 작아야한다를 잘 수행했다면 잡음일 뿐…
주석으로 처리한 코드
주석으로 처리한 코드가 왜 주석처리되어있는지를 설명하고 있지 않다면 삭제하는 것이 좋다.
HTML 주석
Javadocs 등으로 주석을 뽑아 웹페이지에 올릴 생각이라면 주석에 HTML태그를 삽입해야 하는 책임은 도구가 져야한다.
전역 정보
주석을 달아야 한다면 근처에 있는 정보만 달 것.
만약 전역정보 등 멀리 있는 정보를 주석으로 달면 이후 해당 정보가 변해도 주석도 최신화될 것이란 보장은 어디에도 없음.
너무 많은 정보
모호한 관계
즉, 설명을 해야할 주석에 설명이 필요하면 필요없다.
비공개 코드에서 JAVAdocs
공개 api에서 Javadocs는 유용하지만 공개하지 않을 코드라면 필요 없음.
스터디 의문점 질문 및 답변
Q1
주석으로 처리한 코드
주석으로 처리한 코드만큼 밉살스러운 관행도 드물다. 다음과 같은 코드는 작성 하지 마라!
이번 2주차의 4단원을 읽고 나서 살짝 당황했습니다. Toy Project를 만들 때마다 해당 코드를 로컬에서 실행하거나 배포 환경에서 실행할 때 포트 번호를 주석으로 관리했었기 때문입니다.
public class Application {
public static void main(String[] args) {
// Local 실행 시에는 아래 주석을 해제하고, 포트 번호를 8080으로 설정하세요.
// SpringApplication.run(Application.class, args).setPort(8080);
// 배포 환경에서 실행할 때는 아래 주석을 해제하고, 포트 번호는 8000으로 설정하세요.
SpringApplication.run(Application.class, args).setPort(8000);
}
}
이런식으로 말이에요! 하지만 이번 단원을 읽어도 어떻게 해결해야할지는 잘 와닿지 않습니다.
해당 부분을 해결 할 수 있는 방법이 있을까요? 아이디어 있으시면 남겨주시면 감사드리겠습니다!
답변
