[ Coding Style Guide ] 05. C언어 - 주석

주석

주석은 코드의 가독성을 유지하는 데 매우 중요하다.

하지만 이와 별개로, 가장 좋은 주석은 코드 자체이다. 즉, 최대한 주석없이도 코드 만으로 이해할 수 있도록 코드를 작성한다.

타입과 변수, 함수 등에 이해할 수 있는 이름을 적용하는 것이 이상한 이름을 짓고 주석으로 설명하는 것보다 낫다.

주석을 작성할 때에는 그 코드를 보고 이해해야 하는 사람을 위해 성실하게 작성한다.

• 주석스타일

  • // 또는 / * * /를 사용하되 일관성 있게 사용한다. 되도록 //를 사용한다.

    주석의 내용과 위치, 작성 방식에 일관성을 가져야 한다.

• 파일 주석

  • 모든 파일의 시작 부분에는 라이선스 문구를 작성하고 그 뒤에 내용에 대한 설명을 작성한다.

• 라이선스

  • 모든 파일은 라이선스 문구를 퐇마한다. 또는 동일 라이선스 범위를 갖는 파일들의 최상위 디렉토리에 라이선스 문구를 포함한 별도의 텍스트 파일을 둔다.

    프로젝트에서 사용하는 적절할 라이선스 문구를 선택한다.

• 파일 내용

  • 모든 파일의 위쪽에는 파일의 내용에 대한 주석을 작성한다.

    .h 파일은 그 안에 정의된 것들과 그들이 사용되는 방식에 대한 설명을 포함한다.

    .c 파일은 구현에 대한 세부사항이나 알고리즘 등에 대한 내용을 포함한다. 해당 내용이 .h 파일읅 읽는 사람에게도 필요할 경우에는 .h파일에 넣고, .c파일에는 해당 내용이 .h파일에 포함되어 있다는 것을 명시한다.

  • .h와 .c 파일에 중복된 내용을 사용하지 않는다.

    언젠가 서로 다르게 된다.

• 함수 주석

  • 함수의 사용방법에 대해서는 함수 구현부에 주석으로 작성한다.

    (오픈 API와 같이 선언부만 공개되는 경우에는 선언부와 구현부에 모두 작성한다)

    모든 함수의 선언 직전에, 그 함수가 무엇이고 어떻게 사용하는지에 대한 설명이 주석으로 작성 되어야 한다.

    단, 함수의 동작방식에 대한 자세한 설명은 언급하지 않는다.

다음과 같은 내용이 포함된다.

- 입력은 무엇이고 출력은 무엇인지
- 함수 내에서 메모리를 할당하는 경우, 호출자가 해제해야 하는지 여부
- 인자 중 어떤 것이 null 포인터가 될 수 있는지
- 함수 사용시 성능 상의 영향이 있는 경우
- 필요 이상으로 자세하게 서술하지 않으며, 설명이 사소한 경우 주석을 생략한다.

• 함수 사용방법에 대한 주석은 doxygen 형식 " / * *"으로 작성한다

  @brief, @param, @return은 필수로 작성한다.

• 함수의 동작방식에 대해서는 함수 구현부에 주석으로 작성한다.

  함수가 동작을 어떻게 수행 하는지에 대해 언급한다.

  함수가 작업을 수행하는 데 까다로운 부분이 있는 경우, 이에 대한 설명을 주석으로 작성한다.

  .h 파일이나 혹은 어딘가에 있을 함수 선언부의 주석을 단순히 반복해서는 안 된다.

• 변수 주석

  • 일반적으로 변수의 이름은 주석이 필요 없도록 이해하기 쉽게 정한다.

• 구조체 멤버 변수

  • 구조체 내 멤버 변수는 그 것이 무엇을 위한 것인지 설명하는 주석을 가지며, doxygen 형식 "/ / /"으로 작성한다.

• 전역 변수

  • 모든 전역 변수는 그것이 무엇이며 어디에 사용되는지에 대한 주석을 가진다.

    // 이 테스트에서 통과한 테스트케이스의 총 개수
    int g_testcase_num = 6;

• 구현 주석

  • 구현에서 까다롭거나, 명백하지 않거나, 흥미롭거나, 중요한 부분은 주석을 작성한다.

  • 까다롭거나, 복잡한 코드 조각은 그 앞에 주석을 작성한다.

  • 명확하지 않은 부분의 줄 끝에는 주석을 작성한다.

    코드와 주석은 스페이스 2개로 분리한다.

    // 충분한 메모리가 있는 경우, 데이터 부분도 mmap으로 처리한다.
    if (mmap_budget >= data_size && !MampData(mmap_chunk_bytes, mlock)) {
        return;        // 오류는 이미 로그에 기록되었다.
    }

  • null pointer나 boolean, 문자로 된 숫자값을 함수에 전달할 때, 그것들이 무엇인지에 대한 주석을 추가하거나 상수를 사용하여 코드가 스스로 설명할 수 있게 한다.

    // 나쁜 예
    bool success = CalculateSomething(interesting_value,
                                     10,
                                     false,
                                     NULL);    // 이 인자들의 의미는?
    
    // 좋은 예 주석추가
    bool success = CalculateSomething(intersting_value,
                                     10,    // 디폴트 기본 값
                                     false,    // 호출이 최고가 아님
                                     null);
    
    // 가장 좋은 예#2 - 상수사용
    const int kDefaultBaseValue = 10;
    const bool kFirstTimeCalling = false;
    bool success = CalculateSomething(interesting_value,
                                     kDefaultBaseValue,
                                     kFirstTimeCalling,
                                     null_callback);

  • 절대로 코드 그 자체를 설명하지 않는다.

• 맞춤법

  • 주석 작성시 맞춤법을 잘 지켜야 한다.

• TODO 주석

  • 아주 임시 목적으로 TODO 주석을 사용할 수 있찌만, 반드시 최대한 빨리 제거한다.

    함께 사용되는 3RD PARTY 의존코드의 TODO주서과 구분하기 위해 TODO::로 작성한다.