如何用 Go 写评论

1[label hello.go]
2package main
3
4import "fmt"
5
6func main() {
7    // Say hi via the console
8    fmt.Println("Hello, World!")
9}

1[label hello.go]
2. . .
3    fmt.Println("Hello, World!") // Say hi via the console
4. . .

 1[label color.go]
 2package main
 3
 4import "fmt"
 5
 6const favColor string = "blue" // Could have chosen any color
 7
 8func main() {
 9    var guess string
10    // Create an input loop
11    for {
12    	// Ask the user to guess my favorite color
13    	fmt.Println("Guess my favorite color:")
14
15                // Try to read a line of input from the user.
16                // Print out an error and exit, if there is one.
17    	if _, err := fmt.Scanln(&guess); err != nil {
18    		fmt.Printf("%s\n", err)
19    		return
20    	}
21
22    	// Did they guess the correct color?
23    	if favColor == guess {
24    		// They guessed it!
25    		fmt.Printf("%q is my favorite color!\n", favColor)
26    		return
27    	}
28    	// Wrong! Have them guess again.
29    	fmt.Printf("Sorry, %q is not my favorite color. Guess again.\n", guess)
30    }
31}

1[label color.go]
2const favColor string = "blue" // Could have chosen any color

 1[label client.go]
 2. . .
 3// refererForURL returns a referer without any authentication info or
 4// an empty string if lastReq scheme is https and newReq scheme is http.
 5func refererForURL(lastReq, newReq *url.URL) string {
 6    // https://tools.ietf.org/html/rfc7231#section-5.5.2
 7    //   "Clients SHOULD NOT include a Referer header field in a
 8    //    (non-secure) HTTP request if the referring page was
 9    //    transferred with a secure protocol."
10    if lastReq.Scheme == "https" && newReq.Scheme == "http" {
11    	return ""
12    }
13    referer := lastReq.String()
14    if lastReq.User != nil {
15    	// This is not very efficient, but is the best we can
16    	// do without:
17    	// - introducing a new method on URL
18    	// - creating a race condition
19    	// - copying the URL struct manually, which would cause
20    	//   maintenance problems down the line
21    	auth := lastReq.User.String() + "@"
22    	referer = strings.Replace(referer, auth, "", 1)
23    }
24    return referer
25}
26. . .

1[label godo.go]
2// Client manages communication with DigitalOcean V2 API.
3type Client struct {

1[label godo.go]
2// Do sends an API request and returns the API response. The API response is JSON decoded and stored in the value
3// pointed to by v, or returned as an error if an API error has occurred. If v implements the io.Writer interface,
4// the raw response will be written to v, without attempting to decode it.
5func (c *Client) Do(ctx context.Context, req *http.Request, v interface{}) (*Response, error) {
6. . .
7}

1[label godo.go]
2    // Ensure the response body is fully read and closed
3    // before we reconnect, so that we reuse the same TCPConnection.
4    // Close the previous response's body. But read at least some of
5    // the body so if it's small the underlying TCP connection will be
6    // re-used. No need to check for errors: if it fails, the Transport
7    // won't reuse it anyway.

 1/*
 2Gofmt formats Go programs.
 3It uses tabs for indentation and blanks for alignment.
 4Alignment assumes that an editor is using a fixed-width font.
 5
 6Without an explicit path, it processes the standard input. Given a file,
 7it operates on that file; given a directory, it operates on all .go files in
 8that directory, recursively. (Files starting with a period are ignored.)
 9By default, gofmt prints the reformatted sources to standard output.
10
11Usage:
12
13gofmt [flags] [path ...]
14
15The flags are:
16
17-d
18Do not print reformatted sources to standard output.
19If a file's formatting is different than gofmt's, print diffs
20to standard output.
21. . .
22*/
23package main

 1[label greeting.go]
 2// This is a doc comment for greeting.go.
 3//  - prompt user for name.
 4//   - wait for name
 5//    - print name.
 6// This is the second paragraph of this doc comment.
 7// `gofmt` (and `go doc`) will insert a blank line before it.
 8package main
 9
10import (
11    "fmt"
12    "strings"
13)
14
15func main() {
16    // This is not a doc comment. Gofmt will NOT format it.
17    //  - prompt user for name
18    //   - wait for name
19    //    - print name
20    // This is not a "second paragraph" because this is not a doc comment.
21    // It's just more lines to this non-doc comment.
22    fmt.Println("Please enter your name.")
23    var name string
24    fmt.Scanln(&name)
25    name = strings.TrimSpace(name)
26    fmt.Printf("Hi, %s! I'm Go!", name)
27}

 1// This is a doc comment for greeting.go.
 2//   - prompt user for name.
 3//   - wait for name.
 4//   - print name.
 5//
 6// This is the second paragraph of this doc comment.
 7// `gofmt` (and `go doc`) will insert a blank line before it.
 8package main
 9
10import (
11    "fmt"
12    "strings"
13)
14
15func main() {
16    // This is not a doc comment. `gofmt` will NOT format it.
17    //  - prompt user for name
18    //   - wait for name
19    //    - print name
20    // This is not a "second paragraph" because this is not a doc comment.
21    // It's just more lines to this non-doc comment.
22    fmt.Println("Please enter your name.")
23    var name string
24    fmt.Scanln(&name)
25    name = strings.TrimSpace(name)
26    fmt.Printf("Hi, %s! I'm Go!", name)
27}

1[label Output]
2This is a doc comment for greeting.go.
3  - prompt user for name.
4  - wait for name.
5  - print name.
6
7This is the second paragraph of this doc comment. `gofmt` (and `go doc`) will
8insert a blank line before it.

1[label problematic.go]
2. . .
3func main() {
4    x := initializeStuff()
5    /* This code is causing problems, so we're going to comment it out for now
6    someProblematicCode(x)
7    */
8    fmt.Println("This code is still running!")
9}