콘텐츠로 건너뛰기

훠닐 표준 주석 가이드라인

훠닐의 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.”).

 

“훠닐 표준 주석 가이드라인”의 2개의 댓글

  1. Embark on an exceptional journey with Dehradun Escorts, where sophistication and allure seamlessly intertwine. Our escorts redefine the core of companionship, ensuring unforgettable moments amidst the tranquil hills of Dehradun. Immerse yourself in the company of skilled and captivating companions dedicated to fulfilling your desires, crafting lasting memories. Elevate your Dehradun experience with our exclusive escort services, infusing your stay with a delightful blend of excitement and charm

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다