[ECCS] 주석의 위치와 내용

2. 주석 규정

2. 2 주석의 위치와 내용

규정

1. 모든 주석은 명료하고 완전한 문장으로 적절한 철자법과 문법 그리고 적절한 구두점을 사용하여 작성되어야 한다.
2. 가장 유용한 주석은 일반적으로 규모가 큰 알고리즘의 한 단계를 수행하는 코드 블록의 앞에 위치한다. 이러한 코드 블록 다음에 꼭 빈 라인을 넣어야 한다. 그리고 이 블록 앞의 주석은 들여쓰기 수준이 같아야 한다.
3. 뻔한 코드에 주석을 달지 않도록 한다. 읽는 이가 C 언어를 안다고 가정하자. 예를 들어, 변수, 함수 이름 및 연산자에의해서 한 줄 코드의 의미가 명확하지 않지만 짧은 주석이 명확히 할 수 있는 경우에만 end-of-line 주석을 사용해야 한다. 특히, 아래와 같이 별 도움이 되지 않으면서 불필요한 주석을 사용하지 않는다.
   numero <<= 2; // Shift numero left 2 bits
4. 각 개별 주석의 개수와 길이는 설명하는 코드의 복잡성에 비례해야 한다.
5. 알고리즘 또는 기술 세부사항이 외부 참조(예: 설계 규격, 특허 또는 교과서)에 정의될 때마다, 코드를 읽는 이가 문서를 찾을 수 있도록 충분한 원본 참조를 주석에 포함해야 한다.
6. 소스코드를 충분히 문서화하기 위해 흐름도 또는 도표가 필요할 때, 그 도면은 소스 코드와 동일하게 버전 관리되어야 하며, 주석에는 도면의 파일 이름 또는 제목을 표시해야 한다.
7. 모든 가정(assumption)은 주석에 기술하여야 한다.
8. 각 모듈 및 함수에는 자동 문서 생성 도구(예를 들어 Doxygen)에 적합한 방식으로 주석처리해야 한다.
9. 중요한점을 강조하기 위해 다음과 같은 대문자 주석 표지를 사용한다.
   1. “WARNING:“는 유지관리자에게 코드를 변경할 위험이 있음을 경고한다. 예를 들어, 지연 루프 카운터의 종단값은 경험적으로 결정되었으며 코드가 포팅되거나 최적화 레벨이 조정될 때 변경해야 할 수 있다.
   2. “NOTE:“는 코드의 “why”(주석에 일반적으로 쓰이는 “how”와 구별)에 대해 설명한다. 예를 들어, 칩에 오류가 있어 드라이버 코드가 데이터 시트와는 다른 경우, 또는 원프로그래머에 의한 가정(assumption)이 있는 경우.
   3. “TODO:“는 코드가 아직 작업중임을 나타내며, 앞으로 남은 작업을 설명한다. 해당되는 경우, TODO단어 앞에 대문자로 된 프로그래머 이름 또는 이니셜을 포함할 수 있다(예: “MJB TODO:“).

예시

// Step 1: Batten down the hatches.
for (int hatch = 0; hatch < NUM_HATCHES; hatch++)
{
  if (hatch_is_open(hatches[hatch]))
  {
    hatch_close(hatches[hatch]);
  }
}

// Step 2: Raise the mizzenmast.
// TODO: Define mizzenmast driver API.

이유

이러한 규정을 따르면 좋은 주석을 작성할 수 있습니다. 좋은 주석은 좋은 코드와 연관이 있습니다. 주석은 그 주석이 나타내는 코드를 작성하기 이전에 작성하는 것이 좋습니다.

불행하게도, 소스 코드와 문서는 시간이 지남에 따라 표류하기 쉽습니다. 이를 방지하기 위한 가장 좋은 방법은 문서를 가능한 한 코드에 가깝게 작성하는 것입니다. 마찬가지로, 이전에 명확하다고 생각했던 코드에 대한 질문이 생길 때마다 그 근처에 해당 이슈에 대한 주석을 추가해야 합니다.

Doxygen은 사용자를 위한 API의 모듈, 함수와 매개변수를 설명하는 문서를 생성하는데 유용한 도구입니다. 그러나 유지보수 비용을 줄이기 위해 함수 몸체 내부에도 주석이 필요합니다.

시행

코드 검토시 주석의 품질을 평가해야 합니다. 코드 검토자는 주석이 코드를 정확하게 설명하고 있는지, 명확하고 간결하며 가치가 있는지 확인해야 합니다. 소프트웨어 빌드시 자동으로 생성된 문서를 다시 작성해야 합니다.