주석 에서

주석 소개

주석을 사용하면 코드가 실행되는 방식에 영향을 주지 않으면서 코드에 메모를 남길 수 있어요. 한 줄 주석은 줄의 어디에서든 //로 시작해요. 컴파일러는 //부터 그 줄의 끝까지 모든 내용을 무시해요. 같은 줄에서 코드 뒤에 주석이 오면 흔히 인라인 주석이라고 불러요. 여러 줄 주석은 줄의 어디에서든 /*로 시작하고 */로 끝나요. 컴파일러는 그 사이에 있는 모든 내용을 무시하는데, 이는 한 줄 또는 여러 줄에 걸칠 수 있어요.

// This is a single-line comment on its own line

x := 1 // This is an single-line comment inline with code
fmt.Println(x) // prints 1

/*
This is a valid
multiline comment.
*/

/* This is also a valid multi-line comment. */

주석은 어디에 위치하느냐에 따라 하는 역할이 달라요.

코드 주석

코드 주석은 무엇을 하는지가 아니라 왜 그렇게 하는지를 설명해요. 어떤 결정을 내린 이유가 코드만 봐서는 분명하지 않을 때 사용해요:

results = results[1:] // skipping the header row

대부분의 경우 잘 작성된 코드는 그 자체로 설명이 되기 때문에 주석이 필요하지 않아요. 때로는 코드가 복잡하거나 예상 밖의 일을 해야 할 때도 있는데, 그런 코드에는 주석을 달아야 해요.

문서 주석

문서 주석은 패키지, 변수, 함수를 문서화할 때 사용해요. 이 문서는 코드를 _사용_하는 방법을 알고 싶어 하는 다른 개발자를 위한 거예요. 코드가 무엇을 하는지, 어떻게 사용하는지를 큰 틀에서 설명해야 해요. 코드 자체가 어떻게 동작하는지에 대한 세부 사항은 포함하지 않아요. 문서 주석은 선언 바로 앞에 위치하며, 주석과 선언 사이에 빈 줄이 없어야 해요. godoc이 이 주석을 분석해서 패키지 문서를 만들어요. pkg.go.dev에서 그 예를 볼 수 있어요. 문서 주석은 식별자의 이름으로 시작해서 마침표로 끝나는 완전한 문장이어야 해요.

외부에 공개된 식별자(대문자로 시작하는 식별자)에 단 문서 주석은 생성된 문서에 나타나요. 공개되지 않은 식별자(대문자로 시작하지 않는 식별자)에 단 문서 주석은 문서에 나타나지 않지만, 코드 안에서 유용한 맥락을 제공해 줄 수는 있어요.

패키지를 설명하는 주석은 패키지 이름으로 시작해서 패키지가 무엇을 하는지 설명해요:

// Package kelvin provides tools to convert temperatures to and from Kelvin.
package kelvin

함수를 설명하는 주석은 함수 이름으로 시작해서 함수가 무엇을 하는지, 인자와 반환 값을 포함해 설명해요:

// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
    return 0
}

변수를 설명하는 주석은 변수 이름으로 시작해서 변수가 무엇을 나타내는지 설명해요:

// TemperatureFahrenheit represents a certain temperature in degrees Fahrenheit.
var TemperatureFahrenheit float64

문서 주석의 전체 규격은 Go 문서 가이드를 참고해요.