[C언어] C 언어의 주석(설명문)

C 언어의 주석(설명문, comment)

정의

• 프로그램에 대한 설명을 작성하는 문장
• 컴파일러는 컴파일시 설명문 영역은 무시한다.
• 설명문은 프로그램의 어느 부분이든 위치할 수 있으며, 길이도 상관 없다.

사용법

• /* 와 */ 사이에 작성한 모든 문장 : 여러 줄에 걸친 긴 설명문을 작성할 때

/*  
    이 부분은 도입부입니다.
    코드를 작성하기 전, 코드 컨벤션 위키를 참고하기 바랍니다.
    author : 누구누구
*/

#include <stdio.h>
int add(int x, int y);

...

• // 기후 이후의 문장 - 그 행의 끝 부분까지 설명문 : 간단한 설명문을 작성할 때

int add(int x, int y); // 더하기 함수의 원형

원리

• C 언어 컴파일러가 전처리(preprocessing) 단계에서 주석을 모두 제거한 뒤 코드를 컴파일한다.

int sum = 0; /* 이 부분은 컴파일 시 완전히 제거됨 */

→ 실제로 컴파일러는 아래처럼 처리한다.

int sum = 0;

주의사항

• 블록 주석은 중첩이 불가능하다.

/* 
  /* 이런 건 오류! */
  중첩 주석은 허용되지 않음
*/

주석을 잘 작성하는 방법

(1) ‘무엇을’ 보다는 ‘왜’를 설명하라

/* 나쁜 예 */
i++;    // i를 1 증가시킨다. -> 코드를 보면 누구나 알 수 있음  

/* 좋은 예 */
i++;    // 다음 루프에서 인덱스를 다시 검사하기 위함 -> 코드의 의도를 알 수 있음

(2) 코드 수정 시 주석도 함께 업데이트

• 오래된 주석은 잘못된 정보가 될 가능성이 높다.
• 틀린 주석은 없는 주석보다 더 위험하다

(3) 함수 헤더 주석

/*-----------------------------------
  함수명 : add
  기능   : 두 정수를 더해 반환
  매개변수 : int x, int y
  반환값 : int (x + y)
-----------------------------------*/
int add(int x, int y) {
    return x + y;
}

• 여러 명이 협업할 때, 함수 헤더 주석은 필수
• 짧고, 목적 중심으로 작성하는 게 좋음

(4) TODO, FIXME 등 태그 활용

// TODO: 입력 예외 처리 추가 필요
// FIXME: 이 부분에서 메모리 누수 가능성 있음

• 유지보수 시 중요한 포인트를 쉽게 찾을 수 있다.

Reference

C 프로그래밍 (김형근, 곽덕훈, 정재화 공저)
C 프로그래밍 강의 (방송통신대 - 이병래)