주석은 프로그래밍 언어를 사용해여 의도를 표현할 능력이 부족하여 쓰게 된다. 주석은 실패이다. 주석을 사용해야 할 상황에서는 코드로 의도를 표현할 방법을 먼저 고민해야 한다.부정확한 주석은 아예 없는 주석보다 나쁘다.
=> 주석은 줄이도록 노력해야 한다😥
주석은 나쁜 코드를 보완하지 못한다
주석을 달아야겠다는 생각이 든다면, 코드를 정리해야 한다.
깔끔하게 주석이 없이 의도를 모두 담은 코드가 주석이 많이 담긴 코드보다 훨씬 좋은 코드이다.
어떻게 주석을 쓸지보다 어떻게 코드를 정리할지를 고민해야 한다.
코드로 의도를 표현하라
주석으로 달려는 내용을 함수로 만들어 표현해도 좋다.
좋은 주석
주석 중에서도 필요하고 유익한 주석이 존재하기도 한다. 하지만 가장 좋은 것은 주석을 달지 않아도 되는 코드이다.
법적인 주석
: 법적인 이유로 주석을 넣어야 하는 경우가 존재한다.
ex) 소스 파일의 첫부분에 저작권 정보와 소유권 정보를 기입한다.
정보를 제공하는 주석
: 함수의 반환값 설명, 정규표현식이 뜻하는 것을 설명
의도를 설명하는 주석
: 구현을 넘어서 결정에 대한 숨겨진 의도를 설명한다.
의미를 명료하게 밝히는 주석
: 의미를 정확히 알 수 있게 설명한다.
assertTrue(a.compareTo(a) == 0); // a == a
assertTrue(a.compareTo(b) != 0); // a != b
assertTrue(a.compareTo(ab) == 0); // ab == ab
assertTrue(a.compareTo(b) == -1); // a < b코드가 의미하는 것을 주석으로 달아놓는다. 하지만 주석이 올바른지 확인할 수 없기 때문에 주의해서 달아야 한다.
결과를 경고하는 주석
: 다른 프로그래머에게 결과를 경고하기 위해 사용한다. 특정한 테스트 케이스에서는 해당 코드의 실행 시간이 너무 오래 걸리는 경우를 알려준다.
TODO 주석
: 앞으로 해야 할 일을 남겨둔다.
프로그래머에게 필요한 주석으로 앞으로 구현해야 할 것이나 삭제해야 할 기능, 더 좋은 이름을 생각해 달라는 등의 주석을 남긴다.
TODO 주석은 수시로 확인하여 필요없는 주석은 삭제해야 한다.
중요성을 강조하는 주석
: 매우 중요한데 그냥 넘어갈 수 있는 부분을 강조하기 위해 사용한다.
나쁜 주석
대다수의 주석이 나쁜 주석에 속한다. 주석은 허술한 코드에 설명을 붙이기 위해 사용하는 것이기 때문이다.
주절거리는 주석
: 주석을 달아야겠다고 생각했다면 충분한 시간을 들여 정확한 주석을 달아야 한다. 주석을 보아도 코드가 이해되지 않아 다른 코드들까지 뒤져보는 일이 생겨서는 안된다.
같은 이야기를 중복하는 주석
: 코드를 보고 이해할 수 있는 내용을 또 주석으로 적어 놓는 것은 좋지 않다.
오해할 여지가 있는 주석
: 주석에 적어 놓은대로 코드가 작동되지 않는 경우, 사용자는 함수의 기능을 오해하게 된다. 정확한 주석을 작성해야 한다.
의무적으로 다는 주석
: 모든 변수에 주석을 다는 것은 좋지 않다. 오히려 코드를 헷갈리게 만든다.
이력을 기록하는 주석
: 예전에는 소스를 관리 해주는 시스템이 존재하지 않아 모듈의 첫부분에 변경 이력을 주석으로 관리하였다. 하지만 현재는 소스 관리 시스템이 존재하므로 기록하지 않아도 된다.
있으나 마나 한 주석
: 새로운 정보는 제공하지 않고, 당연한 이야기만 하는 주석은 필요없다.
/**
* 기본 생성자
*/
protected AnnualDateRule() {
}
/** 월 중 일자 */
private int dayOfMonth;함수나 변수로 표현할 수 있다면 주석을 달지 마라
: 주석의 내용을 함수나 변수로 바꿀 수 있다면 주석을 삭제하고 함수나 변수로 표현해야 한다.
위치를 표시하는 주석
: 소스코드에서 특정 위치를 표시하기 위해
// Actions \\\\\\\\\\\\\\\\\\\\\\\\\\이와 같이 주석을 다는 경우가 있다. 가독성을 낮출 수 있기 때문에 정말 필요한 경우에만 사용하도록 한다.
닫는 괄호에 다는 주석
: 닫는 괄호에 주석을 다는 것보다 함수를 줄이기 위해 노력해야 한다.
공로를 돌리거나 저자를 표시하는 주석
: 해당 코드를 누가 추가했는지 표시하는 주석은 삭제하고, 소스 코드 관리 시스템을 이용해서 관리해야 한다.
주석으로 처리한 코드
: 코드를 주석으로 처리하기보다 지워버려야 한다.
HTML 주석
: HTML 주석은 읽기 힘들다.
전역정보
: 주석을 달 때는 근처에 있는 코드에 대한 설명만 적어야 한다. 코드 전체에 대한 설명을 적어서는 안된다.
너무 많은 정보
: 주석에 너무 많은 정보를 넣으면 안된다. 필요한 정보만 적는다.
모호한 관계
: 사용자가 주석과 코드를 보고 바로 알 수 있도록 주석과 코드는 서로 관련있어야 한다.
함수 헤더
: 이름을 잘 정한 함수가 존재하면 주석을 달지 않아도 된다.
