C 코딩 스타일 가이드 - 주석

본 문서는 소프트웨어 개발 시 준수해야 하는 코딩 스타일을 정의하고 가이드한다.

본 문서의 가이드는 C 언어를 대상으로 하고 있으며 C99 표준이 적용된다(추후 C11 등 최신 표준으로 변경 적용 가능하며, 이에 따라 본 문서의 내용이 일부 변경될 수 있다).

본 문서의 가이드는 구글 C++ 코딩 스타일 가이드(https://google.github.io/styleguide/cppguide.html)를 기반으로 내부적인 필요에 따라 일부 내용을 수정, 변경하여 적용한 것이다.

 

주석

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

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

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

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

 

주석 스타일

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

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

 

파일 주석

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

 

라이선스

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

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

 

 

파일 내용

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

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

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

 

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

언젠가 서로 다르게 된다.

 

함수 주석

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

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

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

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

 

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

 

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

 

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

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

 

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

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

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

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

 

 

변수 주석

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

 

구조체 멤버 변수

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

 

전역 변수

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

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

 

구현 주석

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

 

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

// 덧셈에서 생긴 carry를 고려하여 결과를 2로 나눈다.
// (역자 주: 큰 숫자를 2로 나누는 알고리즘으로 나눗셈을 비트 연산으로
// 처리하되 나눠지지 않는 큰 숫자의 나머지를 carry로 보아 다음
// 나눗셈에 해당하는 비트 연산으로 전달하는 코드이다.)
for (int i = 0; i < result->size(); i++) {
  x = (x << 8) + (*result)[i];
  (*result)[i] = x >> 1;
  x &= 1;
}

 

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

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

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

 

 

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

// 나쁜 예
bool success = CalculateSomething(interesting_value,
                                  10,
                                  false,
                                  NULL);  // 이 인자들의 의미는??


// 좋은 예 - 주석 추가
bool success = CalculateSomething(interesting_value,
                                  10,     // 디폴트 기본값.
                                  false,  // 호출이 최초가 아님.
                                  NULL);  // 콜백 없음.


// 가장 좋은 예#2 - 상수 사용
const int kDefaultBaseValue = 10;
const bool kFirstTimeCalling = false;
Callback *null_callback = NULL;
bool success = CalculateSomething(interesting_value,
                                  kDefaultBaseValue,
                                  kFirstTimeCalling,
                                  null_callback);

 

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

// 나쁜 예
// 이제 b 배열을 통과하는데 만약 i가 있다면 다음 요소는 i+1임이 확실하다.
...       

 

맞춤법

C-17. 주석 작성 시 맞춤법을 잘 지켜 작성한다.

 

TODO 주석

C-18. 아주 임시적으로 TODO 주석을 사용할 순 있지만, 반드시 최대한 빨리 제거한다.

함께 사용되는 3rd party 의존코드의 TODO 주석과 구분하기 위해 "TODO::"로 작성한다(검색 시 본 프로젝트 코드의 TODO만 검색되도록).

 

TODO 주석을 작성할 때에는 다음 정보를 포함한다.

• 작성자 정보
• 코드를 언제까지 업데이트하여 해당 주석을 삭제할 지

 

기타

상식적이고 일관성있게 작성한다.

코드를 수정하는 경우 잠시 주변의 코드를 살펴 그것의 스타일을 판단하고, 해당 코드와 일관성을 가지도록 작성한다.

 

이 스타일 가이드를 따르지 않는 기존 코드와의 일관성을 유지하기 위해 본 가이드라인을 따르지 않을 수 있다.

---

 

파트너스 활동을 통해 일정액의 수수료를 제공받을 수 있음