한빛출판네트워크

저자: 한동훈

[지난기사보기]
프로그래밍 스타일(4)
프로그래밍 스타일(3)
프로그래밍 스타일(2)
프로그래밍 스타일(1)
　
2.4 문서화하라.

프로젝트를 진행하는 동안에 여러분이 작성한 의미없는 문서, 회의시간동안에 남았던 문서들, 프로그램의 버그등을 문서화한 것등의 수 많은 문서가 남아있게 될 것이다. 뿐만 아니라 팀원들의 작업 결과나 작업 진행, 보고서등을 받아보게 될 것이다.

이러한 것들을 팀원들에게 history@xyz.com과 같이 하나의 계정으로 모두 보내도록 하고, 프로젝트가 완료하는 시점에 이것들을 모두 일괄출력해서 보관하도록 한다.

이 문서들은 모두 프로젝트 진행기간 동안 다시 쳐다보는 일도 없을 것이고, 많아야 1-2번 정도 쳐다보게 될 것이다. 그러나 프로젝트가 끝나고 버그가 발생했을 때, 무엇이 문제였는지, 어디를 제일 먼저 확인해야하고 수정해야하는지를 쉽게 찾는 데 도움이 된다.

이러한 것들을 잘 모아두었다면, 프로젝트가 완료되는 시점에서 문서화하는 것도 그리 어려운 것은 아닐 것이다.(적어도 문서화작업이라는 미명하에 처음부터 모든 것을 다시 살펴보는 일은 막을 수 있다)

2.4.1 코드 문서화

코드 문서화는 자바 환경의 JDoc, 닷넷 환경의 NDoc, C/C++과 같은 다양한 언어에 적용할 수 있는 DoxyGen과 같은 문서화도구들이 있다. 이들 도구는 웹에서 바로 이용할 수 있는 HTML, 윈도우 도움말 형식을 비롯해서 PDF 형식으로 만들어주기까지 한다.

이들 도구를 이용하면 코드를 작성하면서 작성한 코멘트가 바로 도움말이 된다. 각 문서화 도구가 제공하는 기능들을 확인해서 프로젝트에 필요한 문서 양식을 공통으로 지정하는 것은 좋은 방법이다. 이런 문서 양식을 미리 작성해 놓은 소스 코드를 시작점으로 삼는 것도 좋은 방법이 될 수 있다. 이런 문서를 뼈대라 하여 뼈대(Skeletion) 문서라고 부른다.

Vim에서도 skel.c/skel.h를 작성해 두고 Template Loader 플러그인을 사용하면 이 파일로부터 새로운 C 소스 코드를 생성할 수 있으며, VS.NET과 같은 개발도구도 템플릿 기능을 이용해서 고유의 프로젝트나 ASP.NET 페이지 양식을 작성할 수 있다. 이러한 도구들을 활용해서 누구나 손쉽게 코드 문서화를 할 수 있는 환경을 구축해야 한다.

참고

Vim Template Loader
ASP.NET 가이드 3. UI 향상 및 사용자 템플릿 만들기

2.5 버그를 기록하라

버그를 기록하는 것이 필요하다. 이러한 버그들을 기록하는 가장 일반적인 형식을 만들어서 팀원들이 모두 같은 양식으로 작성하여 리포트할 수 있도록 해야한다.

대개는 다음과 비슷한 형식이 될 것이다.

- 버그 발견일 : 팀 내부나 테스트 과정에서 버그가 발견되고 보고될 것이다.
- 원인 : 버그의 원인.

기능부호가 H인 경우에 대해서 잘못 처리하는 경우와 같은 로직상의 버그에서부터 참조할 수 없는 메모리를 참조하는 포인트 사용의 오류등과 같이 다양할 것이다.

- 증상 : 버그로 인해 생기는 증상을 자세히 기록한다.

기능부호 H를 소비하는 경우에 신품재고는 그대로 유지되고 재생품재고가 감소해야하는데 신품과 재생품 재고가 모두 감소하는 경우와 같을 것이다.

- 해결책 : 버그를 어떻게 없앴는가.
- 예방법 : 이와 같은 종류의 버그를 예방할 수 있는 방법
- 관련 파일 : 버그가 있는 파일과 버그와 관련되어 같이 변경되어야하는 종속 파일들을 모두 기록한다.
- 최종 수정일 : 누가, 언제 최종적으로 수정했는가

이와 같은 버그 리포트는 모두 bug@xyz.com과 같이 하나의 메일함으로 보내도록 한다. 이렇게 하면 팀원 모두가 어떤 버그가 있었는지 확인할 수 있으며, 프로젝트가 완료후 이러한 기록들을 모두 모아서 버그를 분석할 수 있다.

버그 분석을 통해서 프로젝트에서 사용했던 방법보다 더 빠르고 정확하게 대처할 수 있는 방법을 찾을 수도 있고, 프로젝트 진행 과정에서 어떤 부분에서 버그가 가장 많이 발생했는지 알아낼 수 있고, 진행 과정에 문제가 있는지도 알아낼 수 있다.

버그 리포트는 버그를 발견하는 즉시 작성되어야하며, 수정하지 않거나 미루게 되더라도 bug@xyz.com으로 보내도록 해야한다. 그러나 되도록이면 버그는 발견되는 순간에 제거하도록 해야하며, // fix me와 같이 주석을 남겨서 일을 미뤄서는 안된다.

나중에 코드가 완성된 다음에 버그를 수정하는 경우 나머지 코드와 예기치 않은 오류를 만들어낼 수 있으며, 더욱 더 문제를 어렵게 만들 수도 있다.

1.3 버그 관리에서도 쓴 것처럼 본격적인 버그 관리 도구를 사용하는 것이 바람직하다. 그러나 bug@history.com처럼 작은 변화를 통해 버그 관리의 유용성을 깨닫게 하는 것도 하나의 방법이 될 수 있다.

2.6 변수

변수의 사용에 있어서만큼 프로그래머들에게 많이 이야기 된 것은 없다. 그리고 필자의 몇가지 이야기는 분명히 논쟁거리가 된다는 것을 알고 있다. 아마도, 여러분이 생각하는 상식적인 이야기와 여러분이 생각하기에 비상식적인 이야기로 꽉 찰 것이라는 것이다. 처음에 얘기했듯이 반드시 따라야하는 규칙은 아니다. 마음에 들면 따르고, 마음에 들지 않으면 따르지 않으면 그만이다.

2.6.1 모호한 변수는 사용하지 마라

모호한 변수는 사용하지 마라. 언어에 따라서 variant 형 변수를 지원하거나 지원하지 않을 것이다. 필요하다면 variant를 쓸 수 있지만, 대부분의 경우에는 정확한 데이터 형식을 지정하라. Variant는 사용하지 말아야할 악과 같은 데이터 타입이라고 생각하자.

물론, Perl과 같은 언어는 변수의 데이터 타입이 없으며 variant 타입이 기본 타입이며, 변수에 저장되는 값에 따라서 각각의 서브 타입을 갖고 있다.

그러나 VB와 같은 언어의 경우에 variant 타입과 자동형변환과 같은 암시적 타입 변환은 프로그래머에게 가장 해독한 독과 같다. 암시적 타입 변환의 경우에 언어마다 작동하는 방식이 조금씩 다르기 때문에, 기존 프로그래밍 언어의 지식을 자신이 현재 작업하고 있는 새로운 언어에 작용하는 경우에 여러분이 원하는 대로 작동하지 않게 된다.

A = 123
B = 456

Print A & B
Print A + B
Print "Pay" + A & B

이러한 경우에 여러분은 이것이 어떻게 처리될 지 알 수 없다. A가 정수인지, 문자열인지 알 수 없게 되어 버린다. 따라서 반드시 변수의 타입을 지정해서 사용해야한다.

위에서와 같이 숫자가 문자열로 암시적인 형변환이 일어나는 경우에 해당 언어에 익숙하고, 세세한 것까지 기억하는 프로그래머가 아닌한 틀리기 쉽다. 이러한 경우에는 CStr, CInt, CLng와 같은 함수를 사용해서 변환할 형을 미리 지정해주도록해야한다.(언어에 따라 함수는 다르다)

Variant는 어떤 경우에 사용하는가? 대부분의 경우에 의문을 갖겠지만, VB와 같은 언에서는 컨트롤과 같은 객체를 넘겨받는데 Variant 타입을 사용한다. 그외에 4 * 4와 같이 정사각형의 배열을 만드는 것에 익숙하지만, 경우에 따라 1 행은 7열, 2행은 3열, 3행은 4열과 같은 불규칙 배열이 필요한 경우에 Variant 타입을 쓸 수 있다.(1차원 배열 3개에 대한 컨테이너로 Variant 타입을 이용하는 경우다)

최근의 프로그래밍 언어들은 대부분 변수의 초기값을 설정한다. 숫자형에 대해서는 0, 문자열에 대해서는 문자열의 길이가 0인 문자열, 객체에 대해서는 null로 설정한다. 그러나 이러한 것들이 다른 언어에서 반드시 적용되는 것은 아니다. 변수는 반드시 초기값을 선언하도록 한다.

2.6.2 변수는 나누어 선언한다

int i, j, k;
Dim i, j, k as Integer

첫번째는 C 언어이고 두번째는 VB이다. 이 경우에 첫번째는 3개의 변수 유형이 모두 int 형이지만, 두번째 줄에서는 i, j는 Variant 형이고, k만 Integer 형이 된다. 이와 같이 하나의 언어에서 사용하는 문법이 다른 언어에서는 전혀 다르게 사용될 수 있다. 따라서 위와 같은 코드들은 모두 다음과 같이 고치는 것이 좋다.

Int i;
Int j;
Int k;

Dim i as integer
Dim j as integer
Dim k as integer

이렇게 고침으로서 다른 사람이 코드를 읽고 이해하기 쉬워진다.

위 코드는 또 잘못되어있다. 이 변수들은 모두 초기값을 갖지 않는다. 초기값을 갖도록 선언해야 한다. 또한, 옆에는 각각의 변수가 무엇 때문에 선언되는지 적어야한다.

만약 코드를 작성하는 도중에 필요없게 된 변수가 있어서 코드내에서 해당 변수를 지웠다면 변수의 선언을 지우는 것도 잊지 않도록 한다.

또 다른 예를 살펴보자.

char *string, string2;

C 언어에서 첫번째 변수 string은 char*이지만 두번째 변수 string2는 char가 된다. 이와 같이 C 언어에서는 변수의 선언 여부를 엄격하게 검사하지만, VB와 같은 언어들은 변수의 선언을 엄격하게 검사하지 않는다. 이러한 경우에 VB에서는 Option Explicit등을 사용해서 변수의 선언을 엄격하게 검사할 수 있다. 가장 흔한 실수는 변수명을 PrintPage와 PirntPage와 같이 적는 것이다. 변수 선언 여부를 검사하지 않으면 VB와 같은 언어는 새로운 변수로 생각하여 PirntPage라는 새로운 변수를 생성하게 되고 프로그램이 문제없이 실행되더라도 알지못할 버그를 내포하고 있는 것이다.

2.6.2.1 Option Explicit에 얽힌 이야기

2.6.2에서와 같이 Option Explicit을 사용해서 반드시 사용하는 변수를 선언해서 사용해야한다라는 것은 사람들에 따라 의견이 분분하다. VBScript, VBA를 사용하다가 VB를 사용하는 프로그래머나 Perl 프로그래머들은 그러한 것들을 사용하는 것은 오히려 거추장 스러운 것이라고 얘기한다. 반면에 처음부터 VB를 사용한 프로그래머나 C/C++과 같이 변수 선언을 엄격하게 검사하는 언어를 사용하다가 VB를 사용하는 프로그래머들은 반드시 Option Explicit을 써야한다고 말한다.

아주 능숙한 프로그래머중에도 Option Explicit을 사용하지 않아도 되며 타이핑 오류를 잡는 데에 아주 능숙한 프로그래머들도 많다.

결국, 어떠한 방식을 선택하느냐는 여러분의 몫이다.
필자는 대부분의 언어에서 변수 선언을 검사하기를 좋아한다.