훠닐 표준 주석 가이드라인

훠닐의 C++ 주석 스타일은 구글 C++ 스타일 가이드의 주석 스타일을 기본으로 한다. 

기본

//, /* */ 둘다 사용가능하지만 // 을 주로 사용하도록 한다.

파일 주석

파일의 가장 첫 부분에 저작권, 라이선스, 원작자 등에 대한 내용을 작성한다.

• 헤더파일(.h)에는 파일에 속한 클래스, 함수 등이 어떻게 쓰이는지에 대한 요약 설명을 작성한다.
• 구현파일(.cpp)에는 구현에 관련된 좀더 상세한 설명을 하고 까다로운 알고리즘에 대한 설명도 추가한다.
• .h, .cpp간 주석을 중복되지 않도록 한다.

클래스 주석

해당 클래스가 무엇을 위해 존재하고 어떻게 사용하는지에 대한 내용을 작성한다.

클래스의 인스턴스가 멀티 쓰레드에 의해 접근 가능할 경우 접근 규칙 및 그에 대한 추가 설명을 작성한다.

예)

// Iterates over the contents of a GargantuanTable.  Sample usage:
//    GargantuanTable_Iterator* iter = table->NewIterator();
//    for (iter->Seek(“foo”); !iter->done(); iter->Next()) {
//      process(iter->key(), iter->value());
//    }
//    delete iter;
class GargantuanTable_Iterator {
  …
};

 함수 주석

함수 선언(Function Declarations)

함수 선언 앞에 주석이 위치해야하며 어떤이 함수가 무엇을 하고 어떻게 사용되는지에 대해 설명한다. 함수가 어떻게 그 일을 수행하는지에 대한 내용은 함수 정의에 기술합니다.

 예)

// Returns an iterator for this table.  It is the client’s
// responsibility to delete the iterator when it is done with it,
// and it must not use the iterator once the GargantuanTable object
// on which the iterator was created has been deleted.
//
// The iterator is initially positioned at the beginning of the table.
//
// This method is equivalent to:
//    Iterator* iter = table->NewIterator();
//    iter->Seek(“”);
//    return iter;
// If you are going to immediately seek to another place in the
// returned iterator, it will be faster to use NewIterator()
// and avoid the extra seek.
Iterator* GetIterator() const;

함수 정의(Function Definitions)

각 함수에 대해 무엇을 하고 헷갈리는 부분에 대해 설명합니다. 트릭을 사용했다면 그 방법과 다른 대안을 대신하여 왜 트릭을 사용했는지에 대해 기술합니다.

변수 주석

변수명은 최대한 무엇으로 사용되는지를 나타내야 하며 의혹이 생기지 않도록 더 자세한 설명을 작성합니다.

클래스 데이터 멤버(Class Data Members)

무엇을 위해 사용되는지 작성한다.

예)

private:
// Keeps track of the total number of entries in the table.
// Used to ensure we do not go over the limit. -1 means
// that we don’t yet know how many entries the table has.
int num_total_entries_;

전역 변수(Global Variables)

마찬가지로 무엇을 위해 사용되는지 작성한다.

// The total number of tests cases that we run through in this regression test.
const int kNumTestCases = 6;

구현 주석

예)

// Divide result by two, taking into account that x
// contains the carry from the add.
for (int i = 0; i < result->size(); i++) {
  x = (x << 8) + (*result)[i];
  (*result)[i] = x >> 1;
  x &= 1;
}

// If we have enough memory, mmap the data portion too.
mmap_budget = max<int64>(0, mmap_budget – index_->length());
if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock))
  return;  // Error already logged.

 

파라미터 설명

잘못된 예)

bool success = CalculateSomething(interesting_value,
                                  10,
                                  false,
                                  NULL);  // What are these arguments??

다음과 같이 바뀌어야 함

bool success = CalculateSomething(interesting_value,
                                  10,     // Default base value.
                                  false,  // Not the first time we’re calling this.
                                  NULL);  // No callback.

또는

const int kDefaultBaseValue = 10;
const bool kFirstTimeCalling = false;
Callback *null_callback = NULL;
bool success = CalculateSomething(interesting_value,
                                  kDefaultBaseValue,
                                  kFirstTimeCalling,
                                  null_callback);

구두점, 맞춤법, 문법

완전한 문장으로 읽기 쉽게 작성한다. 쉼표 등을 적절히 활용하여 좀더 읽기 좋게 작성한다.

TODO

TODO는 임시적으로 혹은 짧은 시간에 작성되거나 충분하긴 하지만 완벽하지 않은 부분에 대해 할것을 말할 때 사용한다.

TODOs should include the string TODO in all caps, followed by your name, e-mail address, or other identifier in parentheses. A colon is optional. The main purpose is to have a consistent TODO format searchable by the person adding the comment (who can provide more details upon request). A TODO is not a commitment to provide the fix yourself.

// TODO(kl@gmail.com): Use a “*” here for concatenation operator.
// TODO(Zeke) change this to use relations.

If your TODO is of the form “At a future date do something” make sure that you either include a very specific date (“Fix by November 2005”) or a very specific event (“Remove this code when all clients can handle XML responses.”).