VBA 기본 문서화 기법

VBA 기본 문서화 기법은 프로젝트 규모와 무관하게 코드 가독성과 유지보수성을 높이는 데 핵심적인 역할을 한다. 특히 조직 내에서 장기적으로 VBA 매크로를 운영하거나, 다른 개발자와 협업할 때는 VBA 기본 문서화 기법을 체계적으로 익혀두어야 문제 발생 시 신속하게 대처할 수 있다.

문서화 중요성과 구성 요소

VBA 코드는 다른 프로그래밍 언어에 비해 비교적 짧고 단순하게 보이기 쉽다. 그러나 문서화를 제대로 하지 않으면, 프로젝트가 커질 때마다 변수와 함수 의도를 파악하기 어려워지고 오류 발생 시 원인 파악이 늦어진다. 이를 방지하기 위해 다음과 같은 구성 요소를 고려한다.

주석(Comment)
- 코드 상에 간략한 설명을 붙여 함수 목적, 인수 의미 등을 표시
- ' (작은따옴표)나 Rem 키워드를 사용해 한 줄 주석 작성
- 여러 줄 주석은 각 줄마다 '를 반복 사용
프로시저(함수·서브) 설명
- 각 함수와 서브프로시저 상단에 용도, 파라미터, 반환값, 예외 상황 등을 문서화
- 유지보수 담당자가 쉽게 목적을 파악하도록 상세히 기술
변수 선언부 주석
- 핵심 변수를 선언할 때, 해당 변수가 어떤 데이터를 저장하는지 간략한 주석을 붙여 혼동을 줄임
모듈·클래스 설명
- 모듈 또는 클래스 파일 상단에 전체 목적과 주 사용처를 기록
- 대규모 프로젝트에서 구조를 빠르게 이해하도록 도움
버전 관리 정보
- 작성자, 작성일, 수정 이력, 버전 번호 등을 주석으로 포함해 변경 사항 추적 용이

주석 스타일 가이드

1) 한 줄 주석

가장 간단히 '을 사용해 작성한다. 여러 줄 작성 시 각 줄마다 '를 쓰는 것이 규칙이며, 코드와 주석을 구분하기 쉽게 들여쓰기를 적절히 적용한다.

```vb
' 이 서브프로시저는 보고서를 자동 생성한다.
' Input: shtName - 대상 워크시트 이름
' Output: 없음
Public Sub GenerateReport(ByVal shtName As String)
    ' sht 변수로 워크시트 개체를 담는다.
    Dim sht As Worksheet
    Set sht = ThisWorkbook.Sheets(shtName)

    ' 보고서 타이틀 입력
    sht.Range("A1").Value = "월간 보고서"

    ' ...
End Sub


위 코드에서 주석만 봐도 서브프로시저 기능, 파라미터 의미를 빠르게 파악할 수 있다. 이런 식으로 VBA 기본 문서화 기법을 적용하면 코드 해석이 훨씬 쉬워진다.

### 2) 중요 구간 구분
중요한 로직이나 다른 개발자가 자주 수정을 가할 부분에 주석 구획을 넣는다. 예를 들어 `'==== Main Logic ====` 같은 구분선을 추가해 모듈 전체를 시각적으로 나눈다.

```vb
```vb
'==== 데이터 초기화 구간 ====
' 이 부분에서 변수나 시트 상태를 초기화
Call ResetSheet(sht)

'==== 메인 로직 구간 ====
' 입력값을 바탕으로 계산을 수행
Call CalculateStats(sht)

'==== 결과 출력 구간 ====
' 최종 계산된 결과를 셀에 배치
Call OutputResults(sht)


이처럼 큰 구간을 시각적으로 명확히 나누면, 다른 사람이 수정을 진행할 때 필요한 영역을 빠르게 찾을 수 있다.

## 프로시저(함수·서브) 문서화 전략

프로시저는 VBA에서 기능 단위로 묶이는 핵심 구성 요소다. 함수(Function)와 서브(Sub) 모두 동일한 전략으로 문서화할 수 있다.

1. **프로시저 헤더**  
   - 프로시저 상단에 목적, 인수, 반환값(함수인 경우), 예외 상황 등을 주석으로 정리  
   - 팀 내 표준 템플릿을 마련해 일관성 유지

2. **예외 처리 방안**  
   - 런타임 오류 발생 가능성이 큰 부분에 `On Error GoTo` 문을 배치하고, 어떤 오류가 언제 발생 가능한지 주석에 기술  
   - 에러 발생 시 Err.Description으로 구체적인 로그를 남기게끔 세팅

3. **인수(매개변수) 설명**  
   - `ByVal`, `ByRef` 여부, 자료형, 값 범위 등을 간단히 메모  
   - 파라미터가 많다면, 구조체나 클래스에 묶는 방법도 고려

4. **반환값 설명** (함수일 경우)  
   - 함수 마지막에서 어떤 형태의 데이터를 넘기는지 정확히 언급  
   - 반환값이 의미하는 바를 명확히 해두면 코드 흐름 파악이 수월

```vb
```vb
'-----------------------------------------
' Function Name: GetEmployeeAge
' Purpose     : 사원 번호를 받아 해당 사원의 나이 정보를 반환
' Parameters  : ByVal empID As Long - 사원 고유 번호
' Return      : Long - 나이(만 나이 기준)
' Usage       : result = GetEmployeeAge(1001)
'-----------------------------------------
Public Function GetEmployeeAge(ByVal empID As Long) As Long
    Dim age As Long

    ' 예외 상황: empID가 0 이하인 경우는 잘못된 입력
    If empID <= 0 Then
        Err.Raise 1000, "GetEmployeeAge", "유효하지 않은 사원 번호"
    End If

    ' 실제 DB나 시트 연동 로직 (예시로 하드코딩)
    age = 30  ' 임의값

    GetEmployeeAge = age
End Function


이런 식의 서술형 주석을 붙여두면, 함수 작성자 본인뿐 아니라 후임 개발자나 동료가 코드를 읽을 때도 목적과 사용법을 쉽게 이해한다.

## 변수와 상수 문서화

VBA 프로젝트 규모가 커질수록 변수와 상수가 여러 곳에서 공용으로 사용될 수 있다. 관리가 어려워지기 전에 주석을 통해 다음 정보를 구체적으로 명시한다.

- **변수 용도**  
  - 숫자형(특히 Long, Integer, Double)인 경우 어떤 범위의 값을 의미하는지  
  - 문자열(파싱, 파일 경로, 사용자 입력 등)일 때 어떠한 데이터를 저장하는지  
- **전역 변수와 상수**  
  - 모듈 상단에 Public 변수나 Enum, Const를 정의한다면, 다른 모듈에서 사용 가능  
  - 사용 목적, 혹은 허용 범위 등을 주석으로 달아두면 혼동 방지

```vb
```vb
Option Explicit

'***********************************
' 상수 선언: 사원 등급별 기본 급여 상수
'***********************************
Public Const GRADE_A_BASE As Long = 3000000
Public Const GRADE_B_BASE As Long = 2500000
Public Const GRADE_C_BASE As Long = 2000000

'***********************************
' 전역 변수: 현재 사용자 ID
' 로그인 시스템에서 인증 후 할당됨
'***********************************
Public g_CurrentUserID As String


이처럼 상수와 전역 변수를 모두 모듈 상단에 배치하고, 용도를 한눈에 파악할 수 있게 하면 유지보수와 협업에 상당히 유리하다.

## 모듈·클래스 헤더 정보

코드가 들어 있는 모듈(표준 모듈, 폼 모듈, 클래스 모듈 등)을 처음 열었을 때, 그 목적과 구조를 재빨리 이해하도록 헤더를 작성한다. 보통 모듈 상단에 주석 형태로 작성한다.

- **모듈 이름**  
  - 예: `Module_DBAccess`, `Module_Utils`, `Class_Employee`  
  - 기능 분류가 명확해지도록 접두어 사용
- **주요 기능 요약**  
  - DBAccess 모듈이면 DB 연결, 쿼리 실행, 로그 기능 등을 총괄한다  
  - Utils 모듈이면 문자열 처리, 날짜 처리, 공용 함수 집합 등을 제공
- **작성자, 작성일, 수정 이력**  
  - 대규모 프로젝트에서 수정 이력을 간단히 남겨두면, 변경 추적이 편해진다

```vb
```vb
'===============================
' 모듈 이름: Module_DBAccess
' 주요 기능:
'   - DB 연결 (ADO)
'   - SQL 쿼리 실행
'   - 오류 처리 및 로그 작성
'
' 작성자   : 홍길동
' 최초 작성: 2025-02-01
' 수정 이력:
'   2025-02-05 - 기능 추가: Stored Procedure 호출
'===============================
Option Explicit

Public Sub OpenDBConnection()
    ' ...
End Sub

' ...


클래스 모듈의 경우에도 비슷하게 작성하되, 해당 클래스가 어떤 속성과 메서드를 주로 제공하는지 요약해둔다.  

## 문서화 보조 도구 활용

문서화를 일일이 수작업으로 진행해도 되지만, 대규모 프로젝트에서는 자동화 도구나 Excel 기반 문서화 시트를 병행해 볼 수 있다.

- **VBE(Visual Basic Editor) 내 Export**  
  - 모듈을 .bas, .frm, .cls 파일로 내보내 버전 관리 시스템(Git 등)에 보관  
  - 주석을 포함한 코드가 그대로 텍스트 파일로 관리되어 변경 이력 확인 가능
- **주석 템플릿**  
  - 반복되는 형식을 빠르게 입력하기 위해 주석 템플릿(예: Function Header, Class Header)을 미리 만들어 매번 복사·붙여넣기  
- **문서화 애드인**  
  - 일부 Excel VBA 커뮤니티나 서드파티 애드인 중에 VBA 프로젝트 문서화(프로시저 목록, 변수 목록)를 자동 생성하는 기능을 갖춘 것이 있다

## 예외 처리와 로깅에 대한 문서화

코드 상에서 오류를 처리하는 로직은 종종 복잡해진다. 이때 주석 없이 방치하면 “왜 이 부분에서 Err.Raise를 했는지”, “왜 특정 오류 번호를 사용했는지”를 알기 어렵다.

1. **오류 번호, 오류 메시지**  
   - 특정 에러 상황에서 `Err.Raise 2001, "ModuleName", "오류 사유"` 같은 식으로 명시  
   - 주석으로 “2001번 오류는 파일 미존재”처럼 의미를 알기 쉽게 작성
2. **로그 파일 관리**  
   - 파일로 로그를 남길 때, 로그 경로와 파일명 규칙을 주석으로 기록  
   - 로그 포맷(YYYY-MM-DD HH:MM:SS [ERROR] Message 등)을 정의하고 모듈 상단이나 별도 문서화
3. **회피 전략**  
   - 오류가 발생했을 때 재시도할지, 사용자에게 메시지를 표시할지, 특정 폴더를 생성할지 등 정책을 주석으로 남긴다

```vb
```vb
'-----------------------------------------
' Sub Name   : LoadDataFromFile
' Description: 지정된 CSV 파일에서 데이터를 읽어 워크시트에 적재
' Error Info :
'   - 3000: 파일 찾을 수 없음
'   - 3001: CSV 포맷 에러
'-----------------------------------------
Public Sub LoadDataFromFile(ByVal filePath As String)
    On Error GoTo ErrHandler

    If Dir(filePath) = "" Then
        Err.Raise 3000, "LoadDataFromFile", "파일을 찾을 수 없음"
    End If

    ' CSV 파싱 로직
    Call ParseCSV(filePath)

    Exit Sub
ErrHandler:
    Select Case Err.Number
        Case 3000
            ' 로그 남기기
            Call WriteLog("File not found: " & filePath)
            MsgBox "파일이 존재하지 않습니다: " & filePath
        Case 3001
            ' CSV 포맷 오류
            Call WriteLog("CSV format error: " & filePath)
            MsgBox "CSV 파일 포맷이 잘못되었습니다."
        Case Else
            ' 알 수 없는 오류
            Call WriteLog("Unknown error (" & Err.Number & "): " & Err.Description)
            MsgBox "알 수 없는 오류가 발생했습니다."
    End Select
End Sub


위 예시는 문서화를 통해 오류 번호와 메시지를 명확히 정의했다. 이런 형태는 VBA 기본 문서화 기법의 핵심 사례라 할 수 있다.

## 표준 코딩 컨벤션과 문서화

VBA는 언어 자체가 비교적 자유로운 편이라, 변수명, 상수명, 프로시저명 스타일이 제각각이면 프로젝트가 난잡해질 수 있다. 사내 코딩 컨벤션을 정해두고 문서화하면 협업 효율이 오른다.

- **변수명 접두어**  
  - 예: `strName`, `lngCount`, `bolCheck`  
  - 자료형을 접두어로 붙여 타입 추론을 쉽게
- **상수명**  
  - 전부 대문자로, 단어 사이에 언더스코어(`_`) 사용 예: `CONST_MAX_ROW`, `CONST_MIN_AGE`
- **프로시저명**  
  - 동사+목적어 형태, 예: `LoadData`, `CalculateTotal`, `SetUserInfo`
- **클래스명**  
  - PascalCase, 예: `ClassEmployee`, `CustomerManager`

이러한 컨벤션을 문서로 정리하고, 실제 코드와 주석에도 일관되게 적용하면 자연스럽게 VBA 기본 문서화 기법이 정착된다.

## 대규모 프로젝트 시 문서화 팁

1. **주기적 리뷰**  
   - 일정 간격으로 문서화 상태를 점검해, 주석이 실제 코드와 일치하는지 확인  
   - 수정된 로직에 맞춰 주석을 갱신하는지 모니터링
2. **자동화 스크립트**  
   - Export된 .bas, .cls, .frm 파일을 grep 등의 도구로 스캔해, TODO나 FIX 같은 키워드를 추출하여 문서화 상태를 점검
3. **변경 이력 관리**  
   - Git, SVN 등 버전 관리 시스템을 활용해 누가 언제 어떤 주석을 수정했는지 추적  
   - 대규모 팀이라면 문서화 품질도 코드 리뷰 프로세스 일부로 삼는다

## 작성된 문서 예시

아래는 Excel VBA에서 문서화한 실제 예시를 간단히 보여준다.

```vb
```vb
'*********************************************************************
' 모듈 이름: Module_SalesProcess
' 기능 요약:
'   - 일일 판매 데이터를 집계하고 요약 보고서 시트를 생성
'   - 외부 ERP 시스템에서 CSV 파일 가져오기
'   - 사내 포맷에 맞춰 데이터 변환
'
' 작성자: 김유신
' 최초 작성: 2025-01-10
' 수정 이력:
'   2025-01-15 - 보고서 시트 컬럼 구조 변경
'*********************************************************************
Option Explicit

Public Sub ProcessDailySales(ByVal fileName As String)
    On Error GoTo ErrHandler

    '=== CSV 파일 파싱 ===
    Dim rawData As Variant
    rawData = ReadCSV(fileName)  ' ReadCSV는 별도 모듈에 정의

    '=== 데이터 검증 ===
    If IsEmpty(rawData) Then
        Err.Raise 4000, "ProcessDailySales", "CSV 데이터가 비어 있음"
    End If

    '=== 결과 시트 생성/초기화 ===
    Dim shtResult As Worksheet
    Set shtResult = CreateOrClearSheet("DailySales")

    '=== 메인 로직: 합계, 평균, 수량 계산 ===
    Call SummarizeData(rawData, shtResult)

    '=== 보고서 형식 지정 ===
    Call FormatReport(shtResult)

    Exit Sub
ErrHandler:
    Select Case Err.Number
        Case 4000
            MsgBox "CSV 파일에 데이터가 없습니다."
        Case Else
            MsgBox "알 수 없는 오류: " & Err.Description
    End Select
End Sub

이 예시는 모듈 상단 주석을 통해 기능 요약, 작성자, 수정 이력을 명기했고, 프로시저 내에서 섹션별로 주석을 달아 로직을 구분했다. 에러 처리부에도 번호와 메시지를 사용해, 문제 상황을 명확히 확인할 수 있다.