함수 주석 (Function Comments)¶

선언 주석은 함수의 사용을 설명합니다(명백하지 않은 경우). 함수 정의의 주석은 작업을 설명합니다.

거의 모든 함수 선언에는 함수의 기능과 사용 방법을 설명하는 주석이 바로 앞에 있어야 합니다. 이러한 주석은 함수가 간단하고 명확한 경우에만 생략할 수 있습니다(예: 클래스의 명확한 속성에 대한 간단한 접근자). .cc 파일에 선언된 전용 메서드 및 함수는 면제되지 않습니다. 함수 주석은 주어가 "This function"인 것처럼 암시적으로 쓰고, 3인칭 동사구로 시작해야 합니다. 예를 들어 "Open the file"(명령형)이 아니라 "Opens the file"(파일을 연다)처럼 씁니다. 일반적으로 이러한 주석은 함수가 작업을 수행하는 방법을 설명하지 않습니다. 대신, 함수 정의의 주석에 남겨야 합니다.

함수 선언의 주석에서 언급할 사항 유형:

입력과 출력은 무엇입니까? 함수 인수 이름이 '백틱'으로 제공되면 코드 인덱싱 도구가 문서를 더 잘 표시할 수 있습니다.
클래스 멤버 함수의 경우: 객체가 메서드 호출 기간 이후에 참조 또는 포인터 인수를 기억하는지 여부. 이는 생성자에 대한 포인터/참조 인수에서 매우 일반적입니다.
각 포인터 인수에 대해 null이 허용되는지 여부와 null이면 어떻게 됩니까?
각 출력 또는 입력/출력 인수에 대해 해당 인수의 상태는 어떻게 되나요?(예: 상태가 추가되었거나 덮어써졌습니까?)
함수 사용 방식이 성능에 영향을 미치는 경우.

예는 다음과 같습니다.

// Returns an iterator for this table, positioned at the first entry
// lexically greater than or equal to `start_word`. If there is no
// such entry, returns a null pointer. The client must not use the
// iterator after the underlying GargantuanTable has been destroyed.
//
// This method is equivalent to:
//    std::unique_ptr<Iterator> iter = table->NewIterator();
//    iter->Seek(start_word);
//    return iter;
std::unique_ptr<Iterator> GetIterator(absl::string_view start_word) const;

그러나 불필요하게 장황하게 설명하거나 완전히 명백한 내용을 언급하지 마세요.

함수 재정의를 문서화할 때 재정의된 함수의 설명을 반복하기보다는 재정의 자체의 세부 사항에 집중하세요. 대부분의 경우 재정의에는 추가 문서가 필요하지 않으므로 설명이 필요하지 않습니다.

생성자와 소멸자에 주석을 달 때, 코드를 읽는 사람은 생성자와 소멸자가 무엇인지 알고 있으므로 "이 객체를 파괴합니다"와 같은 주석은 유용하지 않다는 점을 기억하십시오. 생성자가 인수로 수행하는 작업(예: 포인터의 소유권을 가져오는 경우)과 소멸자가 수행하는 정리 작업을 문서화합니다. 이것이 사소한 경우 댓글을 건너 뛰십시오. 소멸자에게 헤더 주석이 없는 것은 매우 일반적입니다.

함수가 작업을 수행하는 방식에 대해 까다로운 점이 있는 경우 함수 정의에 설명 주석이 있어야 합니다. 예를 들어 정의 주석에서 사용하는 코딩 트릭을 설명하거나, 수행하는 단계에 대한 개요를 제공하거나, 실행 가능한 대안을 사용하는 대신 이전 방식으로 함수를 구현하기로 선택한 이유를 설명할 수 있습니다. 예를 들어 함수의 전반부에서는 잠금을 획득해야 하지만 후반부에서는 왜 필요하지 않은지 언급할 수 있습니다.

.h 파일이나 다른 곳에서 함수 선언과 함께 제공된 주석을 반복해서는 안 됩니다. 함수가 수행하는 작업을 간략하게 요약하는 것은 괜찮지만 주석의 초점은 함수가 수행하는 방식에 맞춰져야 합니다.

이해하기 쉽게 설명하기¶

핵심: 선언 주석 = "무엇을", 정의 주석 = "어떻게"¶

선언 주석(.h): 함수를 어떻게 쓰는지를 설명. 주어를 "This function"으로 보고 3인칭 동사구로 시작하세요 — "Open the file"(명령형)이 아니라 "Opens the file"(연다). 자명한 단순 접근자 등은 생략 가능(단 .cc의 private 함수도 면제는 아님).
정의 주석(.cc): 함수가 어떻게 동작하는지(코딩 트릭, 단계 개요, 그 구현을 택한 이유 등)를 설명. 선언 주석을 그대로 반복하지 마세요.

선언 주석에 담을 것¶

입력과 출력 (인수 이름은 백틱으로 감싸면 도구가 잘 표시함)
참조·포인터 인수를 호출 이후에도 객체가 보관하는지 (생성자에서 흔함)
포인터 인수에 null이 허용되는지, 허용되면 어떻게 되는지
출력/입출력 인수의 상태가 어떻게 바뀌는지(추가? 덮어쓰기?)
사용 방식이 성능에 영향을 주는 경우

생성자·소멸자¶

"이 객체를 파괴한다" 같은 자명한 주석은 쓰지 마세요. 생성자가 인수로 하는 일(예: 포인터 소유권 획득), 소멸자가 하는 정리만 문서화하고, 사소하면 생략하세요(소멸자에 헤더 주석이 없는 건 흔합니다).