2 분 소요

함수의 주석을 작성하고자 할때 여러분은 어디에 작성을 하시나요?

당연히 헤더 파일에 있는 함수 선언부나 소스 파일에 있는 함수 구현부에 적게 될텐데요. 팀원들의 관습상 선호하는 방식이 상당히 다르죠. 대부분 다음의 3가지 성향을 보입니다.

  1. 헤더 파일에 작성해야 합니다.

  2. 소스 파일에 작성해야 합니다.

  3. 헤더 파일, 소스 파일 모두 작성해야 합니다.

소스 파일에 작성해야 한다는 분들의 의견을 들으면 다음과 같이 주장합니다.

“헤더 파일은 단순한 축약 형태이기 때문에 한눈에 간결히 볼 수 있어야 하고, 헤더 파일이 길어지면 안됩니다. 그래서 소스 파일에 함수 주석을 작성해야 합니다. 또 분석을 할 때에는 함수 선언부 보단 함수 구현부를 참조하는 경우가 더 많으므로 소스 파일에 주석을 작성하는 것이 도움이 됩니다.”

맞는 말입니다. 함수 분석을 할때 함수 구현부를 참조하게 되죠. 만약 함수 구현부 위에 함수 주석이 있다면 분석에 정말 많은 도움이 됩니다. 하지만 한가지, 정말 중요한 이유로 헤더 파일에는 반드시 함수 주석이 있어야 합니다.

여러분이 작성한 함수나 클래스를 라이브러리로 만들고, 혹은 Dll로 만들고 다른 누군가에게 제공해야 한다면, 함수 구현부를 숨겨야만 합니다. 아무 설명없는 헤더 파일을 제공한다면 사용자는 참으로 난감해 질 수 있습니다. 별도로 메뉴얼을 만들겠다는 욕심은 버리는게 좋습니다. 따로 교육시키겠다는 욕심도 버리는게 좋습니다. 시시각각 변하는 코드에 즉각적으로 대응할 수 없기 때문이죠.

그렇다면, 헤더 파일에만 작성한다면 어떻까요? 헤더 파일의 주석을 읽고, 상황에 따라 소스코드의 구현부를 보게 되겠네요. 파일을 번갈아 보게 되니 눈이 어지러워지고, 심신이 허해질 수도 있습니다.

좋습니다. 헤더 파일, 소스 파일에 모두 작성하는 방법은? 초기에는 괜찮은듯 보입니다. 다른 사용자에게 라이브러리 형태로 제공하더라도 무리가 없고, 소스 분석에도 용이합니다. 하지만 유지보수를 하면서 점점 귀찮아 지기 시작하는 군요. 두군데의 주석을 동기화 해야 하니 말이죠. 결국 시간이 지남에 따라, 헤더의 주석과 소스의 주석이 달라지기 시작하고, 어느것이 맞는 것인지 점점 난감해 지기 시작합니다.

각각이 모두 장단점을 가지고 있으니 뭐가 진리인지 판단하기 힘드시죠? 저도 힘드네요. 분명한건 팀이나 회사에서 원칙을 정해야 한다는 것입니다. 다음처럼요.

  1. 헤더 파일에 함수 주석을 적지 않는다. 단, 외부에 노출되는 헤더의 경우에는 소스 파일의 함수 주석을 복사해 넣는다.(소스 파일의 함수 주석이 진짜다)

  2. 헤더 파일에 함수 주석을 적는다. 단 소스 파일의 구현부를 분석하는데 필요하다면 헤더 파일의 함수 주석을 복사해 넣는다.(헤더 파일의 함수 주석이 진짜다)

  3. 헤더 파일, 소스 파일 모두 함수 주석을 적는다. 한쪽이 변경되면 다른 쪽에도 반드시 동기화 하라.

1번의 경우는 외부로 노출되는 헤더 파일만 소스파일과 주석을 동기화하면 됩니다.

2번의 경우 팀원이 바뀌고 유지 보수 되면서 여러사람이 소스를 분석하다보면 헤더 파일의 주석이 모두 소스 파일로 복사되게 될 겁니다. 결국 3번의 경우처럼 모든 헤더 파일과 소스파일의 주석을 동기화 해야 하죠.

3번의 경우는 작성된 모든 파일에 대해서 주석을 동기화 해야 합니다.

1번의 경우가 아무래도 주석 동기화가 적겠죠? 외부로 노출되는 헤더 파일만 동기화하면 되니까요. 그래서 전 오래도록 1번을 선호했었습니다.

하지만, 최근에는 헤더 파일에 함수 주석을 적는 2번을 사용하고 있습니다. 그리고, 소스 파일의 구현부를 분석할 필요가 없도록 함수 원형을 직관적으로 만들도록 노력하고 있습니다.(사실 정말 힘든 작업이죠… ㅋㅋ)

아무튼, 무얼하던간에,

잊지마세요.

  1. 함수 주석 작성에 대한 대원칙을 잡으세요. 헤더와 소스중 어떤게 !!!진짜!!!인가요?

댓글남기기