주석을 최소화할 것

주석은 최소한으로 남기는 게 좋습니다. 어떤 사람은 주석이 훌륭한 문서화 역할을 한다고 생각해서 주석을 가능한 한 많이 달려고 하는데, 그것은 잘못된 습관입니다. 불필요한 주석은 좀 더 가치 있는 일에 사용될 수 있었던 낭비된 노력이며, 코드를 이해하는 데 오히려 방해가 됩니다. 이런 점에서 볼 때, 팀 외부에 문서를 공개하지도 않을 것인데 닥시젼(doxygen) 같은 도구를 활용해 모든 멤버 함수와 멤버 변수에 주석을 남기고 그걸 문서로 만드는 것은 안 좋은 발상입니다. 주석은 어떤 정보를 코드만으로 전달할 수 없을 때에만 필요합니다. 만약 어떤 주석을 코드로 바꿀 수 있거나 생략해도 별로 문제가 없다면, 그 주석은 불필요한 주석입니다.

이해가 쉽도록, 예를 들어 보겠습니다.

// 객체를 생성한다.
create_object();

위에 쓰인 주석은 쓸모없는 주석입니다. 주석이 코드가 명확히 나타내는 함수 역할을 중복해서 설명하고 있습니다. 저 주석을 달려고 한 줄이 낭비되었고, 만약 일일이 타자를 했다면 스물다섯 번의 필요없는 타자가 필요했습니다.

예를 하나 더 들어 보겠습니다. 다음처럼 어떤 일련의 문장이 공통된 하나의 목표를 이루기 위한 작업일 때, 대개 맨 위에 주석을 다는 때가 잦습니다. 왜냐하면 상위 수준에서 코드를 이해하기 쉽게 만들기 때문입니다. 하지만 이런 경우라면 해당 블록을 함수로 떼 내는 게 낫고, 그렇게 하기 어려울 때에만 주석을 다는 게 좋습니다. 해당 블록을 함수로 떼 내면, 기존 함수는 길이가 짧아져서 읽기 쉬워지고 떼 낸 함수는 다른 곳에서 재사용할 수 있어서 좋습니다.

// 어떤 것을 한다.
do_something_1();
do_something_2();
do_something_3();

그런데 우리가 주석을 줄여야 하는 결정적인 이유는, 불필요한 주석이 단지 노력 낭비로 끝나는 게 아니라 코드를 이해하는 데 오히려 방해가 되기 때문입니다. 잘못된 설명이 달린 주석은, 코드와 주석 중에 무엇이 맞는지 판단하기 어렵게 합니다. 참고로 저는 이럴 때에 코드를 항상 믿습니다. 주석의 어떤 설명도 100% 믿지는 말아야 해석을 정확하게 할 수 있습니다.

주석이 꼭 필요한 때는 다음 두 가지뿐입니다. 그건 왜 그 코드가 필요한지 설명해야 할 때, 그리고 코드에 어떤 개선이 필요함을 적어 두어야 할 때입니다. 그리고 꼭 필요하진 않지만 주석이 있으면 때에 따라 좋은 때는, 코드 여러 줄의 의미를 추상적으로 짧게 설명할 때입니다. 주석은 꼭 필요한 곳에만 사용되어야 하며, 권장돼선 안 됩니다.

Advertisements

답글 남기기

아래 항목을 채우거나 오른쪽 아이콘 중 하나를 클릭하여 로그 인 하세요:

WordPress.com 로고

WordPress.com의 계정을 사용하여 댓글을 남깁니다. 로그아웃 / 변경 )

Twitter 사진

Twitter의 계정을 사용하여 댓글을 남깁니다. 로그아웃 / 변경 )

Facebook 사진

Facebook의 계정을 사용하여 댓글을 남깁니다. 로그아웃 / 변경 )

Google+ photo

Google+의 계정을 사용하여 댓글을 남깁니다. 로그아웃 / 변경 )

%s에 연결하는 중