#1. 주석은 기능구현 전에 작성하라

일단 기능구현을 하고 나중에 주석을 적을께요.

글쎄요. 몇년 경험해 보니, 본의 아니게 달콤한 거짓말이 될때가 많았습니다.

또한 기능구현을 하고 난 뒤 주석을 적는다면, 그 주석은 오히려 눈을 어지럽히는 쓸데없는 문장들이 될 확률이 높아져 버리더군요. 기능구현시의 철학과 가정은 모두 사라지고, 완료된 기능에 대한 몇자의 끄적임만 하게 되는것 같습니다.

기능구현을 한뒤 주석을 적게 되면 다음과 같은 오류를 범하게 됩니다.

1. 기능구현시에 사소한 실수를 합니다. 애초에 생각했던 것중 한두개 정도를 빼먹고 구현하는 실수죠. 이게 나중에 엄청난 버그를 유발할 수도 있죠.

2. 주석을 대충 적습니다. 나중에 다시 보니 일일이 주석달기도 귀찮고, 다른 팀원이 닥달하니 형식적으로 대충 뭔가를 적습니다. “a 변수에 1을 더하여 b에 대입한다.” 는 식의 주석이 작성돼 있곤 합니다.

3. 주석을 !!!복사!!! 합니다. 코드와는 전혀 상관없는 엉뚱한 내용이 복사되어 있곤 합니다. 움… 아예 주석이 없는 것이 오히려 좋겠군요. 잘못된 주석은 잘못된 코드보다 더 !!!위험!!!하니까요.

또, 기능구현을 한 후 주석을 적겠다고 할때는 대부분 다음의 변명을 하게 됩니다.

1. 개발 일정이 너무 촉박해요.

2. 지금 번뜩이는 이 생각을 빨리 코드로 옮겨야 해요.

하지만, 저는 개발일정이 촉박할수록 더 주석을 작성해야 한다고 생각합니다. 코딩중 초반 몇개월이 지나면 기능구현보다는 기존 소스코드의 !!!분석!!!에 대부분의 시간을 할애하기 때문에, 초반부터 소스코드 분석에 용이하도록 코드를 작성하셔야 합니다. 주석을 작성하지 않는다면, 몇개월뒤 자신이 짠 코드나 다른 팀원이 짠 코드를 분석하는데 대부분의 시간을 보내게 됩니다. 본인뿐만 아니라 다른 팀원의 개발 생산성을 !!!저하!!!시키는 주 원인이 돼죠.

그리고, 번뜩이는 생각은 코드 보다는 우리나라 말로 후다닥 적는게 더 빠르다고 생각합니다. 정말 코딩의 신이라 빠르게 개발하는 분이라면, 뭐 할 말 없습니다만, 저는 의사코드로 미리 적는 것을 추천합니다. 그리고, 이걸 잘 관리하면, 나중에 진짜 유용한 주석이 됩니다.

번뜩이는 생각을 빠르게 코딩하다 보면 실수로 한두개 정도를 빼먹게 되지만, 자신의 생각을 의사코드로 빠르게 정리한 후 기능 구현을 하게 되면, 한두개 빼먹고 구현하는 실수를 미연에 방지할 수 있습니다. 주석도 작성되고 버그도 미연에 방지할 수 있죠.

그래서 전 항상 코딩을 하기 전에 주석을 먼저 적습니다.

1. 내가 작성할 함수가 무얼 수행해야 하는지 적습니다.

2. 이 함수에 필요한 인수가 무엇이고, 제약사항이 무엇인지 적습니다.

3. 함수 수행에 필요한 사전 가정, 사후 가정을 적습니다.

4. 함수의 리턴값이 어떠한 의미를 가지는지 적습니다.

5. 함수가 실패했을때 어떻게 오류를 처리하는지 적습니다.

6. 함수내에서 어떠한 기능들을 수행해야 하는지 해당 절차를 적습니다.

주석을 다 적었으면 이제 코딩을 시작하죠. 주석을 읽고, 주석의 내용대로 코딩합니다. 잘 이해되지 않는 주석이 있으면, 주석의 내용을 다듬고 변경합니다. 이러면, 코딩시 사소한 실수를 미연에 방지할 수 있고, 몇개월뒤에 코드 분석하다 헤매게 될 자신에게 큰 도움을 줄 수 있습니다.

단기적인 개발일정은 늘어나 보이지만, 전체적인 개발일정은 향상될 것입니다. 유지보수도 효율적으로 할 수 있고요. 이 모든것이 기능구현을 하기전 몇분 정도 자신의 생각을 주석으로 적어 놓기만 하면 됩니다. 덤으로 소스 문서화도 저절로 될 수도 있습니다!!!

기능구현 후 주석을 작성한다면, 이미 사소한 실수를 했을 뿐만 아니라, 코드보다 더 이해하기 힘들고 정확하지 않은 설명만 작성할 뿐입니다. 오히려 코드를 분석하는데 눈만 어지럽혀서 코드 분석을 더 힘들게 만들수도 있죠. 차라리 없는게 더 낫습니다.

잊지 마세요.

1. 주석은 기능구현 전에 작성하여야 합니다.

2. 주석은 구현된 기능을 설명하는 것이 아니라 구현전에 자신의 생각을 !!!정리!!!하는 것입니다.