소개
이전 연습 문제에서는 Go에서 주석을 작성하는 두 가지 방법을 살펴봤어요. 바로 //가 앞에 붙는 한 줄 주석과 /*와 */로 감싸는 여러 줄 주석 블록이에요.
문서 주석
Go에서 주석은 코드를 문서화하는 데 중요한 역할을 해요.
godoc 명령은 이런 주석을 추출해 Go 패키지에 대한 문서를 만들어요.
문서 주석은 설명하는 대상의 이름으로 시작해서 마침표로 끝나는 완전한 문장이어야 해요.
주석은 패키지 앞에 와야 하고, 익스포트된 식별자, 예를 들어 익스포트된 함수, 메서드, 패키지 변수, 상수, 구조체 앞에도 와야 해요. 이런 것들은 다음 연습 문제에서 더 자세히 배워요.
패키지 수준 변수는 이렇게 생겼어요.
// TemperatureCelsius represents a certain temperature in degrees Celsius.
var TemperatureCelsius float64
패키지 주석
패키지 주석은 패키지 절(package x) 바로 앞에 써야 하고, 이렇게 Package x ...로 시작해야 해요.
// Package kelvin provides tools to convert
// temperatures to and from Kelvin.
package kelvin
함수 주석
함수 주석은 함수 선언 바로 앞에 써야 해요.
함수 이름으로 시작하는 완전한 문장이어야 해요.
예를 들어 함수 Calculate의 문서 주석은 Calculate ... 형태여야 해요.
또한 함수가 어떤 인자를 받고, 그 인자로 무엇을 하는지, 반환값이 무엇을 의미하는지 설명해야 하며, 마침표로 끝나야 해요):
// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
return 0
}
지침
고블리노쿠스는 일기 예보를 아주 진지하게 여기는 나라예요.
이름난 데다 책임감 있고 실력도 뛰어난 개발자인 여러분에게, 고블리노쿠스 여러 도시의 현재 날씨 상태를 예측하는 프로그램을 만들어 달라고 부탁했어요.
마침 그때 바빠서 친구 한 명에게 대신 이 일을 부탁했어요.
얼마 후, 고블리노쿠스의 대통령이 연락을 해 와서는 친구가 짠 코드를 이해할 수 없다고 했어요.
코드를 확인해 보니, 친구는 책임감 있는 프로그래머답게 행동하지 않았고 코드에는 주석이 하나도 없었어요.
고블린들도 프로그램을 이해할 수 있도록 프로그램을 명확하게 설명해야겠다고 느꼈어요.
1. package weather 문서화하기
고블린들은 여러분만큼 똑똑하지 않아서, 이 패키지가 자기들에게 무엇을 해 주는지 잊어버렸어요.
package weather가 무엇을 담고 있는지 설명하는 주석을 작성해 보세요.
패키지 주석은 패키지를 소개하고, 패키지 전체와 관련된 정보를 제공해야 해요.
2. CurrentCondition과 CurrentLocation 변수 문서화하기
고블리노쿠스의 대통령은 조금 편집증적이라, 주석이 없는 변수가 나라를 파괴하는 데 쓰일까 봐 두려워해요.
패키지 변수 CurrentCondition과 CurrentLocation의 용도를 분명히 설명해서 대통령이 안심할 수 있게 해 주세요.
그러면 패키지를 사용하는 사람이라면 누구든, 이 변수들이 어떤 정보를 저장하는지와 그 정보로 무엇을 할 수 있는지 알 수 있어요.
3. Forecast() 함수 문서화하기
고블리노쿠스의 예보 담당자들은 Forecast() 함수가 무엇을 하는지 알고 싶어 해요. (다만 어떻게 동작하는지는 알려 주지 마세요. 안타깝게도 그들은 더 혼란스러워질 테니까요.)
이 함수가 하는 일은 설명하되, 어떻게 하는지는 담지 않는 주석을 작성해 보세요.
학습 연습 문제
