Simple is Beautiful(Go 의 문서 작성 규칙)

https://golang.org/pkg 와 https://golang.org/src 는 golang 에 대한 모든 것을 찾아볼 수 있는 보물창고같은 곳이다.
주석을 통해 자동으로 작성된 문서에서 패키지를 개발한 개발자의 의도를 읽을 수 있을 뿐만 아니라 소스 코드까지 아주 쉽게 찾아볼 수 있다.

golang 을 공부하다보면 golang.org/pkg 사이트를 수시로 들어가 보게 된다.
go 에서 제공하는 standard library 들에 대한 정보가 가장 체계적으로 잘 설명되어 있는 곳이기 때문이다.
가끔 go 언어에서 제공하는 문서화 규칙이 너무나 간단한 것에 놀라게 된다.
익히 알다시피 golang.org/pkg 에서 제공하는 문서도 결국 소스에 주석으로 작성된 것을 보기 좋게 보여줄 뿐이다.
함수나 변수, 상수 뿐 아니라 패키지에 대한 정보, Example 코드 등도 모두 업무를 하다보면 자연스럽게 작성하게 되는데, 이러한 것들에 대한 작성 규칙이 너무나 간단한 데다가 추가적으로 문서화 작업을 할 필요가 없다.

https://golang.org/pkg 에서 보여지는 문서들은 어떤 방식으로 작성되고 보여지는 것인지 한번 살펴보자.
이를 잘 활용하면 내 자신이 만드는 패키지들도 완성도 높고 이용하기 쉬운 문서를 별다른 노력없이 제공할 수 있을 것이다.

document 라는 Sample 패키지의 작성 과정을 통해 이를 알아본다.
파일 이름은 myPackage.go 로 작성한다.
myPackage 패키지는 PI 라는 상수와 GetStrLen(), GetDouble() 이라는 두 가지 함수가 정의되어 있다.

// 이 패키지는 go 언어의 문서 작성 규칙이 얼마나 간단한지 보여주기 위한 것이다.
// 아주아주아주 단순하다.
package document

// PI 는 상수이자 전역변수이다.
// 이런 부분은 코드 자체로 이해할 수 있다면 굳이 주석을 달지 않다도 된다.
const PI = 3.14159265

// GetStrLen() 함수는 string 의 길이를 구하는 함수이다.
func GetStrLen(s string) int {
    if s == "" {
        return 0
    }
    n := 0
    for range s {
        n++
    }
    return n
}

// GetDouble() 함수는 주어진 정수의 제곱을 리턴한다.
func GetDouble(n int) int {
    return n * n
}

아래 코드는 위에서 작성된 document 패키지에 대한 Example 코드이다.
Example 코드를 아래와 같이 작성하면 해당 함수에 대한 테스트 뿐 아니라 자동 문서화가 가능하다.
파일 이름은 myPackage_test.go 로 작성한다.
myPackage.go 와 myPackage_test.go 파일 모두 document 라는 패키지 디렉토리 아래에 존재하면 된다.

package document

import (
    "fmt"
)

func ExampleGetStrLen() {
    fmt.Println(GetStrLen("I am Rain.i"))
    fmt.Println(GetStrLen(""))
    // Output:
    // 11
    // 0
}

func ExampleGetDouble() {
    fmt.Println(GetDouble(9))
    fmt.Println(GetDouble(1))
    // Output:
    // 81
    // 1
}

아래와 같은 간단한 과정을 통해 위에서 작성한 코드를 이용한 웹 페이지 문서를 너무나 쉽게 접근할 수 있게 된다.

// 작성한 패키지를 $GOPATH/pkg 로 install 한다.
$ go install github.com/cloudrain21/studygo/document

// 현재의 GOPATH 환경변수
$ echo $GOPATH
  /Users/dplee/work/golang

// package 가 정상적으로 install 되었다.
$ ls -al pkg/darwin_amd64/github.com/cloudrain21/studygo/document.a
  -rw-r--r--  1 dplee  staff  2662 Feb 22 21:30 pkg/darwin_amd64/github.com/cloudrain21/studygo/document.a

// 웹브라우저로 document 를 보기 위해 godoc 유틸리티를 이용하여 web server 를 기동한다. 
// (port 는 변경할 수 있다.)
$ godoc -http=":8080"
using GOPATH mode

웹 브라우저를 기동하고 주소창에 localhost:8080 을 입력하면 아래 그림과 같이 "Third Party" 부분에 자신이 Local 에 작성했던 package 목록이 모두 보이는 것을 확인할 수 있다.
아래 그림의 중간 쯤에 위에서 작성한 document package 에 대한 항목이 있는 것을 볼 수 있다.

document 항목을 클릭해보면 위에서 코드 작성 시 추가했던 주석을 바탕으로 놀랍게도 정갈한 문서가 완성되어 있다.
심지어 함수의 이름을 클릭하면 위에서 작성했던 myPackage_test.go 의 코드를 바탕으로 Example 코드까지 쉽게 확인할 수 있다.

이 뿐만이 아니다.
웹 브라우저 주소 창에 localhost:8080/src 를 입력하면 무엇이 보이는지 확인해보라.
go standard library 뿐 아니라 자신이 작성한 패키지들에 대한 소스 코드를 모두 확인할 수 있다.

https://golang.org/pkg 와 https://golang.org/src 는 모두 위와 같은 방식으로 제공되는 것이다.
go standard library 중에서 bytes 패키지가 제공하는 Compare() 라는 함수(https://golang.org/pkg/bytes/#Compare)를 살펴보자.

Compare() 함수에 대한 설명은 어디에서 추출된 것이겠는가?
바로 https://golang.org/src/bytes/bytes.go 코드에서 추출된 것이다.

그리고, 문서 상에서 보여주는 Example 코드의 출처는 바로 https://golang.org/src/bytes/example_test.go 파일이다. example_test.go 파일은 go test 를 통해 bytes 패키지내의 함수들을 테스트할 수 있을 뿐 아니라 위처럼 자동으로 Example 코드를 문서화하는 데에도 사용된다.

문서를 확인하는 또 한가지 놀라운 방법이 있는데, 바로 go doc 유틸리티를 이용하는 방법이다.
go doc <package name> [함수이름] 명령을 사용하면 command line 으로도 마치 man page 처럼 패키지 설명을 쉽게 찾아볼 수 있다.

$ go doc document GetStrLen                                                                                                                  130 ↵
package document // import "github.com/cloudrain21/studygo/document"

func GetStrLen(s string) int
    GetStrLen() 함수는 string 의 길이를 구하는 함수이다.

정리해보자.

• go 가 제공하는 document tool 은 $GOPATH/src 아래에 작성된 각종 패키지 코드들을 참고하여 문서화를 수행한다.
• 코드에 작성된 문서는 web server 기동 후 웹 브라우저를 통해 확인할 수 있다. (https://xxxxx/pkg)
  이 때 자신이 작성한 패키지에 대한 문서(Third Party) 뿐 아니라 standard library 의 문서까지 함께 보여준다.
• 문서는 go doc 명령을 통해 man page 처럼 확인할 수도 있다.
• 코드 내용(Example 코드 및 각종 테스트 코드)는 https://xxxxx/src 에서 확인할 수 있다.
• (참고)go standard library 의 코드는 go 가 설치된 디렉토리 쪽을 참고하여 문서화하게 된다.

정말 Simple 하고 깔끔하지 않은가?
단순함이 가장 아름다운 것이라는 말을 실감나게 한다.

결론.

당신은 정해진 간단한 규칙에 따라 코드(패키지, 테스트코드, Example 코드)를 작성하라.
그러면, go 는 모든 문서를 당신을 위해 자동으로 만들어줄 것이다.
즉, 당신이 관리해야하는 것은 당신이 작성한 코드 뿐이다.
그 안에 모든 것이 있다.

References
1. https://golang.org/pkg/
2. https://golang.org/src/