이 글은 Effective Go를 일부 번역한 글입니다.

주석

Go는 C 방식 /* */ 구역 주석과 C++ 방식 // 줄 주석을 제공한다. 줄 주석은 표준이다. 구역 주석은 패키지 주석에 사용하지만, 식 안에 써넣기 좋으며, 코드를 덩어리째로 비활성화하기에 좋다.

godoc 프로그램은 (그리고 웹 서버는) Go 소스 파일을 읽어 패키지 내용에 대한 문서를 만들어 낸다. 최상위 선언 전에 빈 줄 없이 적어둔 주석은 선언에 덧붙여 해당 항목을 설명하는 글로 사용한다. 이런 종류와 방식의 주석은 godoc가 만들어 내는 문서의 질을 결정한다.

모든 패키지는 패키지 주석이 있어야 한다. 패키지 주석은 package 절 앞에 구역 주석으로 쓴다. 파일이 여러 개인 패키지는 한 파일에만 패키지 주석을 적으면 된다. 어느 파일이든 상관 없다. 패키지 주석은 패키지를 소개하고 패키지 전체에 대한 정보를 담아야 한다. 패키지 주석은 godoc 페이지 맨 처음에 나타나며, 그 문서의 머리말이어야 한다.

/*
Package regexp implements a simple library for regular expressions.

The syntax of the regular expressions accepted is:

    regexp:
        concatenation { '|' concatenation }
    concatenation:
        { closure }
    closure:
        term [ '*' | '+' | '?' ]
    term:
        '^'
        '$'
        '.'
        character
        '[' [ '^' ] character-ranges ']'
        '(' regexp ')'
*/
package regexp

패키지가 간단하다면 패키지 주석도 간단할 수 있다.

// Package path implements utility routines for
// manipulating slash-separated filename paths.

주석에 별표 현수막 같은 추가 서식은 필요 없다. 심지어 만들어 낸 결과물이 고정폭 글꼴로 나타나지도 않는다. 그러니 정렬할 때 칸 비움에 의존하지 말라. godoc가 gofmt처럼 다 해 줄 것이다. 주석은 해석하지 않고 평문 그대로 둔다. 따라서 HTML이나 _this_ 같은 다른 주석은 문자 그대로 나타날 것이니 사용하지 말라. godoc이 바꾸는 건 들여 쓴 글을 고정폭 글꼴로, 프로그램 조각에 알맞게 보여주는 것뿐이다. fmt 패키지의 패키지 주석이 좋은 예다.

내용에 따라, godoc은 주석의 서식도 바꾸지 않을 것이다. 그러니 제대로 잘 보이게 하라. 정확한 철자와 부호, 문장 구조를 사용하고 긴 문장을 줄이라.

패키지 안에선, 최상위 선언 직전에 쓴 주석을 해당 선언의 주석으로 사용한다. 프로그램 외부로 노출된 (대문자로 쓴) 모든 이름에 문서 주석을 달라.

문서 주석은 완전한 문장일 때 가장 좋다. 그래야 자동으로 다양한 표현을 만들 수 있다. 첫 문장을 선언한 이름으로 시작하고 한 문장으로 요약하라.

// Compile parses a regular expression and returns, if successful, a Regexp
// object that can be used to match against text.
func Compile(str string) (regexp *Regexp, err error) {

주석을 항상 이름으로 시작하면 godoc 출력에 grep을 유용하게 사용할 수 있다. 상상해보라. “Compile”이란 이름은 기억 안 나고 정규 표현식 해석(parsing) 함수를 찾고 싶다면 다음 명령을 실행해볼 수 있다.

$ godoc regexp | grep parse

만약 패키지의 모든 문서 주석을 "이 함수는..."으로 시작했다면 grep으로는 이름을 알아낼 수 없었을 것이다. 하지만 이 패키지는 각 문서 주석을 이름으로 시작했기 때문에 결과는 다음과 같을 것이고, 거기에 원하는 단어가 있을 것이다.

$ godoc regexp | grep parse
    Compile parses a regular expression and returns, if successful, a Regexp
    parsed. It simplifies safe initialization of global variables holding
    cannot be parsed. It simplifies safe initialization of global variables
$

Go의 선언 문법은 여러 선언을 모을 수 있다. 문서 주석 하나로 관련된 상수나 변수들을 하나로 묶어 소개할 수 있다. 선언 전체가 보이기 때문에 이런 주석은 종종 의례적일 수도 있다.

// Error codes returned by failures to parse an expression.
var (
    ErrInternal      = errors.New("regexp: internal error")
    ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
    ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
    ...
)

여러 항목을 묶어 그 관계를 나타낼 수도 있다. 다음 예에서 Mutex 하나로 변수들을 보호한다는 걸 알 수 있다.

var (
    countLock   sync.Mutex
    inputCount  uint32
    outputCount uint32
    errorCount  uint32
)

이 게시물을...