8장 - 주석과 변수 선언 규칙: 코드 문서화의 기술 (56)

주석과 변수 선언 규칙: 코드 문서화의 기술

코드는 컴퓨터와 대화하는 언어이지만, 동시에 다른 개발자들과 소통하는 매체이기도 합니다. 주석과 변수 선언 규칙은 이러한 소통을 원활하게 만드는 핵심 요소입니다.

 

주석 작성 규칙: 코드의 설명서

코드의 첫 주석: 프로젝트의 신분증

모든 소스 파일의 시작 부분에는 해당 파일에 대한 기본 정보를 담은 주석을 작성해야 합니다.

포함해야 할 정보:

• 최초 작성자
• 최초 작성일
• 최초 변경일
• 목적
• 개정 이력 (변경자, 변경 일자, 변경 내용)
• 저작권

주석이 없는 경우:

// 주석이 전혀 없어 파일의 목적과 이력을 알 수 없음
class grade{
    ......
}

표준을 따른 주석:

/*
 * 최초 작성자 : 홍길동
 * 최초 작성일 : 20xx.11.20.
 * 최초 변경일 : 20xx.11.30.
 * 목적 : 성적 프로그램
 * 개정 이력 : 홍길동, 20xx.11.20.(ver. 01)
 *            홍길동, 20xx.11.30.(ver. 02)
 * 저작권 : 길동company
 */
class grade{
    ......
}

이러한 헤더 주석은 프로젝트 관리와 유지보수에 필수적인 정보를 제공합니다.

메서드 주석: 함수의 사용 설명서

각 함수나 메서드 앞에는 해당 함수의 사용법과 목적을 명확히 설명하는 주석을 작성해야 합니다.

포함해야 할 정보:

• 목적: 함수가 수행하는 작업
• 매개변수: 입력 값들에 대한 설명
• 반환 값: 출력 값에 대한 설명
• 변경 이력: 함수 수정 내역

주석이 부족한 경우:

// 메서드에 관한 설명이 전혀 없음
class grade{
    public char getGrade(int kor, int eng, int mat) {
        // 구현 내용...
    }
}

완성된 메서드 주석:

/*
 * 목적 : 등급 구하기
 * 매개변수 : kor(국어 점수)
 *           eng(영어 점수)
 *           mat(수학 점수)
 * 반환 값 : grade(등급-A, B, C, D, F)
 * 변경 이력 : 홍길동, 20xx.11.20.(ver. 01)
 *            홍길동, 20xx.01.20.(ver. 02)
 */
class grade{
    public char getGrade(int kor, int eng, int mat) {
        // 구현 내용...
    }
}

주석 작성의 핵심 원칙

1. 코드와 주석의 명확한 구분

원시 코드와 주석이 시각적으로 구별될 수 있도록 적절한 공백이나 탭을 사용합니다.

좋은 구분의 예:

int totalScore = 0;    // 총점을 저장하는 변수
calculateAverage();    // 평균 계산 함수 호출

2. 코드와 주석의 일치성 유지

코드가 변경되면 반드시 관련 주석도 함께 업데이트해야 합니다. 코드와 맞지 않는 주석은 오히려 혼란을 가중시킵니다.

주석을 업데이트해야 하는 경우:

• 함수 인자가 변경되었을 때
• 함수의 동작 방식이 바뀌었을 때
• 반환 값의 의미가 달라졌을 때

3. 주석이 필요한 경우

모든 코드에 주석이 필요한 것은 아닙니다. 다음과 같은 경우에 주석을 작성하는 것이 효과적입니다:

• 함수 인자에 대한 설명
• 복잡한 논리식의 의미
• 간단하지 않은 자료구조의 용도
• 특별한 알고리즘이나 비즈니스 로직

// 복잡한 논리식에 대한 설명
if ((score >= 90 && attendance >= 80) || 
    (score >= 80 && attendance >= 90 && extraCredit > 0)) {
    // 우수학생 조건: 성적90점 이상이고 출석80% 이상 또는
    //                성적80점 이상이고 출석90% 이상이며 가산점 있음
    grade = 'A';
}

변수 선언 및 자료형 규칙: 안전한 코딩의 기초

변수 선언의 효율성

용도가 같은 변수는 한 줄에 선언

관련성이 높은 변수들은 한 줄에 선언하여 코드를 간결하게 만듭니다.

비효율적인 선언:

int a = 0;
int b = 0;

효율적인 선언:

int a = 0, b = 0;

필요한 변수만 선언

사용하지 않는 변수는 코드를 혼란스럽게 만들고 메모리를 낭비합니다.

문제가 있는 코드:

int a = 0;  // a 변수를 사용하지 않는데 선언함
int b = 0;
processData(b);

개선된 코드:

int b = 0;  // 실제로 사용하는 변수만 선언
processData(b);

배열 선언 규칙

배열 크기 명시

배열을 선언할 때는 크기를 명확히 지정하거나 초기화를 통해 크기를 명시해야 합니다.

문제가 있는 선언:

int score[];  // 배열 크기를 알 수 없음

올바른 선언:

int score[5];                    // 크기 명시
int score[] = {1, 4, 7, 9, 10}; // 초기화로 크기 결정

다차원 배열의 초기화

다차원 배열을 초기화할 때는 중괄호를 적절히 사용하여 구조를 명확히 표현합니다.

가독성이 떨어지는 초기화:

int score[2][2] = {1, 4, 7, 9};

구조가 명확한 초기화:

int score[2][2] = {
    {1, 4},
    {7, 9}
};

변수 초기화 규칙

지역 변수의 필수 초기화

지역 변수는 선언과 동시에 초기화해야 합니다. 초기화하지 않으면 예측할 수 없는 값(쓰레기 값)이 들어갈 수 있습니다.

위험한 코드:

int a;  // 초기화되지 않음 - 쓰레기 값 가능성

안전한 코드:

int a = 0;  // 명확한 초기화

자료형 사용 규칙

부호 없는 자료형 표기

부호 없는 정수형 상수를 사용할 때는 끝에 u를 붙여 명확히 표시합니다.

모호한 표기:

#define MIN 20;

명확한 표기:

#define MIN 10u;

포인터 자료형 일치

포인터 변수에 주소를 저장할 때는 자료형이 일치해야 합니다.

자료형 불일치:

int *pKim;
char chi = 'S';
pKim = χ  // int 포인터에 char 주소 저장

자료형 일치:

int *pKim;
int chi = 5;
pKim = χ  // int 포인터에 int 주소 저장

비트 필드 선언

비트 필드는 반드시 unsigned int 또는 signed int 형으로만 선언해야 합니다.

잘못된 비트 필드:

struct st {
    char a : 2;          // char형 사용 - 동작 미정의
    unsigned int b : 3;
};

올바른 비트 필드:

struct st {
    unsigned int a : 2;  // unsigned int형 사용
    unsigned int b : 3;  // unsigned int형 사용
};

실제 개발에서의 활용

코드 리뷰에서의 장점

잘 작성된 주석과 명확한 변수 선언은:

• 리뷰어의 코드 이해 시간 단축
• 버그 발견 가능성 증가
• 코드 품질 향상

유지보수 효율성

• 6개월 후 자신의 코드를 볼 때: 주석이 있으면 빠른 이해 가능
• 팀원 인수인계 시: 체계적인 문서화로 원활한 전달
• 버그 수정 시: 명확한 변수 선언으로 부작용 최소화

자동화 도구 활용

문서 생성 도구

• Doxygen: 주석에서 자동으로 문서 생성
• JSDoc: JavaScript 주석에서 API 문서 생성

정적 분석 도구

• 변수 사용 분석: 선언되었지만 사용되지 않는 변수 탐지
• 초기화 검사: 초기화되지 않은 변수 사용 경고

마치며

주석과 변수 선언 규칙은 코드의 품질과 유지보수성을 결정하는 중요한 요소입니다. 좋은 주석은 코드가 '무엇을' 하는지뿐만 아니라 '왜' 그렇게 하는지를 설명합니다. 명확한 변수 선언은 런타임 오류를 예방하고 코드의 안정성을 높입니다.

코드는 한 번 작성되지만 여러 번 읽힙니다. 미래의 자신과 동료들을 위해 친절한 주석과 안전한 변수 선언을 습관화해보세요.

다음 포스팅에서는 상수, 수식, 문장 작성의 세부 규칙들을 마지막으로 살펴보겠습니다.