파일 주석 (File Comments)

소스 파일(예: .h 파일)이 여러 사용자 대상 추상화(공통 함수, 관련 클래스 등)를 선언하는 경우 해당 추상화 컬렉션을 설명하는 주석을 포함합니다. 미래의 저자가 거기에 맞지 않는 것이 무엇인지 알 수 있도록 충분한 세부 정보를 포함하십시오. 그러나 개별 추상화에 대한 자세한 문서는 파일 수준이 아닌 해당 추상화에 속합니다.

예를 들어, frobber.h 에 대한 파일 주석을 작성하는 경우 frobber.cc 또는 frobber_test.cc 에 파일 주석을 포함할 필요가 없습니다. 반면에, 연관된 헤더 파일이 없는 Registered_objects.cc에 클래스 컬렉션을 작성하는 경우 Registered_objects.cc에 파일 주석을 포함해야 합니다.

작성자 줄이 있는 파일을 크게 변경한 경우 작성자 줄을 삭제하는 것이 좋습니다. 새 파일에는 일반적으로 저작권 표시나 작성자 라인이 포함되어서는 안 됩니다.

---

이해하기 쉽게 설명하기

핵심: 파일이 여러 추상화를 담으면, 그 묶음을 설명하라

한 소스 파일(예: .h)이 사용자 대상 추상화를 여럿 선언한다면, 그 묶음 전체를 설명하는 파일 주석을 두세요. 미래의 작성자가 "무엇이 여기에 어울리고 무엇이 아닌지" 알 수 있을 만큼만. 개별 추상화의 상세 문서는 파일 수준이 아니라 그 추상화 옆에 둡니다.

적용 예

• frobber.h에 파일 주석이 있으면 frobber.cc/frobber_test.cc에는 반복할 필요 없음.
• 연관 헤더가 없는 registered_objects.cc에 클래스 묶음을 둔다면, 그 .cc에 파일 주석을 둡니다.

작성자·저작권 줄

크게 바꾼 파일의 author 줄은 지우는 게 좋습니다. 새 파일에는 보통 저작권 표시나 author 줄을 넣지 않습니다.