주석?!

본 코드는 아쉽게도 정말 실전에서 사용되는 코드이다.

오늘 발견된 웃픔 코드이다. 위에 코드에는 여러가지 문제가 많지만 그중에서 주석에 대해서 이야기를 하고자 한다.

1. JavaDoc 주석

상기 소스코드를 보면 상단에 JavaDoc을 위한 주석이 포진해 있고 하위에는 각 스텝별로 주석이 달려있다.

JavaDoc이 왜 필요할까 부터 우리는 생각을 해봐야 될 것 같다. JavaDoc은 소스코드상에달린 JavaDoc의 주석 규칙을 따르게 되면 코드를 작성하며 나타나는 코드 컴플리에서 변수가 무슨 형인지 어떤 역활을 하는 메서드인지 도움말을 표기해줄 수 있는 아주 유용한 도구이다. 이런 도구가 없으면 별도로 메서드의 선언과 그 파라메터에 대한 정의와 도움말을 작성해야되며 이는 실제 메서드의 정의와 작성의 일치감을 주지 않아 잘 못 된 정보를 나열 할 수 있는 많은 경우의 수를 막아준다.

하지만 JavaDoc은 내가 만든 소스에서 내가 쓰거나 우리팀의 늘상 쓰는 소스의 경우에는 작성하면 오히려 독이 된다. JavaDoc은 내가 만든 클래스, 메서드 등이 내가 아닌 사람 더 나아가 정보를 얻기 힘든 사람들을 위해서 제공되는 도구이다. 같은 팀내에서 같은 네이밍규칙을 쓰며 비슷한 메타포와 함께 서로 충분히 이해할 수 있는 코드를 작성하고 있는 경우에는 JavaDoc으로 자신과 팀원을 도와줘야되는 이유가 없다. 오히려 JavaDoc 주석으로 인하셔 모니터 화면에서 볼 수 있는 소스코드의 내용이 줄어들게 되기 때문에 오히려 코드를 읽는데 힘든 상황을 만들게 된다.

고로 팀내에서 활용하는 소스코드나 제품의 끝단에 들어가는 소스코드에 JavaDoc 주석을 다는 것은 오히려 혼란만 가중 시킬 뿐이다.

2. 쓸데없이 긴 주석 혹은 때론 의미없는 주석

주석은 코드로 설명이 부족한 경우에 추가적인 정보를 주기 위해서 작성하는 것이다. 바꾸어 말하면 코드로 충분히 사람이 읽기 좋은 코드를 작성했다면 주석은 필요하지 않다. 하지만 어떠한 경우에는 주석을 작성해야지만 내용을 이해하기 쉬운 경우가 있다. 이런 경우에 주석이 정말 효과적으로 사용 되는 것이다.

하지만 코드의 행위자체를 설명하는 저 주석을 보라. 주석이 어떤 도움을 주는가? 주석은 그저 자리만 차지하고 있을 뿐이다. 다시 이야기하지만 우리가 모니터 화면을 볼때 한번에 볼 수 있는 코드의 양이 많으면 많을 수록 우리는 코드를 읽는게 편하다. 그래서 어떤이들은 모니터를 세로로 세워서 쓰기도 하지 않는가?!

상기 코드를 보면 별로 도움도 안되는데 코드보다 주석이 몇줄이나 더 차지 하고 있다. 저런 주석은 달지 않는 것 보다 못한 경우이다. 잘 기억해야 된다 주석은 코드의 작동행위가 아니라 그 코드뭉치들의 작동하는 내용에 대해서 설명이 달려 있어야 한다. 코드자체로 그 내용이 이해가 가면 주석이 필요없겠지만 그 내용이 복잡하여 설명이 필요할 경우 주석을 달아야 하는 것이다.

3. 주석의 동기화

우리가 프로그래밍을 처음 배울때 정말 잘 못 배우는 것 중에 하나가 설명이 필요한 경우에 주석을 달아야 한다는 것이다. 주석의 가장 큰 문제는 주석은 강제적인 동기화가 되지 않는다. 메서드 이름이 MethoA이지만 주석에 '본 메서드 MethodB 는 작동이 어쩌고~' 이런 경우 실제 코드의 내용과 주석의 내용의 불일치가 발생한다. 

현실에서 자주 일어나는 문제 중에 하나가 작성된 주석을 본 다음 추가적인 정보나 바뀐 내용을 수정하지 않고 기존 주석은 주석대로 놔두고 또 추가적으로 주석을 다는 것이다. 무엇인가 내가 작성하지 않는 부분을 삭제 한다는 것에 껄끄러움이 있어서 망설이는 것이다. 하지만 이런 것들이 남아서 나중에는 정말 의미없는 주석이 된고 있으나 마나한 주석이 되며, 결국 공간만 차지하여 소스코드를 읽는데 방해만 주는 주석으로 남게 된다.

결국 주석은 동기화가 쉽지 않다는 결론에 도달하게 된다. 동기화가 쉽지 않다는 단점에도 불구하고 필요악으로 사용해야되만 되는 곳에 아주 제한적으로 달아야 한다.

상기 코드를 보면 코드보다 주석이 더 많은 공간을 차지하게 된다. 개발자는 내가 보는 화면을 넘어서는 화면에도 코드가 있을 경우 혼란스럽다. 그래서 코드는 간결해야 한다. 그런데 저렇게 주석으로 공간을 다 차지하고 있다면 얼마나 혼란스럽겠는가? 화면에 보이지 않는 앞부분과 뒷부분을 확인하고 다시 머리속에 외우고 다시 스크롤을 하면서 아래위 스크롤을 수십차례하면서 소스코드를 보는 경험이 개발자라면 한두번 겪은 일이 아닐 것이다. 그런데 그 중요한 코드의 자리에 저런 주석이 덩그러니 죄다 차지하고 있다면 얼마나 큰 낭비이겠는가?

결론

주석만 없애버렸는데 내가 볼 수 있는 코드가 훨씬 많아졌다. 아래위 스크롤을 옮겨가며 기억에 의존해야되는 코드보기가 아니라 실제 코드의 내용을 보고 파악할 수 있다.

주석 달기는 쉽지만 정말 관리하기 힘든 녀석이다. 정말 심각하게 고민하고 생각하여 달아야 되며 항상 최신화를 위해 노력해줘야 한다. 가급적이면 소스코드에 주석이 없어도 읽기 쉬운 코드를 만들자. 생각보다 많은 부분이 주석의 도움없이 충분히 읽기 쉬운 코드로 만들어진다.