欢迎光临
我们一直在努力

如何在Go中写评论

介绍

注释是计算机程序中存在的行,编译器和解释器会忽略这些行。 在程序中包含注释使得代码对于人类更具可读性,因为它提供了关于程序的每个部分正在做什么的一些信息或解释。

根据程序的目的,注释可以作为自己或提醒的注释,也可以编写它们,以便其他程序员能够理解您的代码正在做什么。

一般来说,在编写或更新程序时编写注释是个好主意,因为以后很容易忘记你的思考过程,而后面写的注释在长期内可能没那么有用。

注释语法

Go中的注释以一组正斜杠( // )开头,并继续到行尾。 在正斜线组之后有一个空白区域是惯用的。

通常,评论看起来像这样:

// This is a comment

注释不会执行,因此在运行程序时不会显示注释。 注释在人类阅读的源代码中,而不是计算机执行。

在“Hello,World!”程序中,评论可能如下所示:

hello.go
package mainimport (    "fmt")func main() {    // Print “Hello, World!” to console    fmt.Println("Hello, World!")}

在迭代切片的for循环中,注释可能如下所示:

sharks.go
package mainimport (    "fmt")func main() {    // Define sharks variable as a slice of strings    sharks := []string{"hammerhead", "great white", "dogfish", "frilled", "bullhead", "requiem"}    // For loop that iterates over sharks list and prints each string item    for _, shark := range sharks {        fmt.Println(shark)    }}

注释应与其评论的代码在相同的缩进处进行。 也就是说,没有缩进的函数定义将具有没有缩进的注释,并且下面的每个缩进级别将具有与它正在评论的代码对齐的注释。

例如,以下是main功能的注释方式,并在代码的每个缩进级别后面添加注释:

color.go
package mainimport "fmt"const favColor string = "blue"func main() {    var guess string    // Create an input loop    for {        // Ask the user to guess my favorite color        fmt.Println("Guess my favorite color:")        // Try to read a line of input from the user. Print out the error 0        if _, err := fmt.Scanln(&guess); err != nil {            fmt.Printf("%s\n", err)            return        }        // Did they guess the correct color?        if favColor == guess {            // They guessed it!            fmt.Printf("%q is my favorite color!\n", favColor)            return        }        // Wrong! Have them guess again.        fmt.Printf("Sorry, %q is not my favorite color. Guess again.\n", guess)    }}

评论是为了帮助程序员,无论是原始程序员还是其他人在项目上使用或协作。 如果无法与代码库一起正确维护和更新注释,则最好不要包含注释,而不是编写与代码相矛盾或相矛盾的注释。

在评论代码时,您应该寻找代码背后的原因而不是代码的内容 除非代码特别棘手,否则查看代码通常可以回答什么如何 ,这就是为什么评论通常围绕着原因

阻止评论

块注释可用于解释您不希望读者熟悉的更复杂的代码或代码。

您可以在Go中以两种方式创建块注释。 第一种是使用一组双正斜杠,并为每一行重复它们。

// First line of a block comment// Second line of a block comment

第二种是使用开始标记( /* )和结束标记( */ )。 对于文档代码,始终使用//语法被认为是惯用的。 您只能使用/* ... */语法进行调试,我们将在本文后面介绍。

/*Everything herewill be considereda block comment*/

在此示例中,块注释定义了MustGet()函数中发生的情况:

function.go
// MustGet will retrieve a url and return the body of the page.// If Get encounters any errors, it will panic.func MustGet(url string) string {    resp, err := http.Get(url)    if err != nil {        panic(err)    }    // don't forget to close the body    defer resp.Body.Close()    var body []byte    if body, err = ioutil.ReadAll(resp.Body); err != nil {        panic(err)    }    return string(body)}

在Go中导出函数的开头看到块注释是很常见的; 这些注释也是生成代码文档的原因。 当操作不那么简单并因此需要彻底解释时,也会使用块注释。 除了记录函数之外,您应该尽量避免过度评论代码并相信其他程序员理解Go,除非您是为特定的受众编写的。

内联评论

内联注释出现在语句的同一行,遵循代码本身。 与其他评论一样,它们以一组正斜杠开头。 同样,在正斜杠之后不需要有空格,但这样做被认为是惯用的。

通常,内联注释如下所示:

[code]  // Inline comment about the code

内联注释应谨慎使用,但可以有效地解释棘手或非显而易见的代码部分。 如果您认为您可能不记得将来编写的代码行,或者您与可能不熟悉代码的所有方面的人合作,它们也会很有用。

例如,如果您在Go程序中没有使用大量数学,那么您或您的协作者可能不知道以下内容会创建一个复数,因此您可能希望包含一个内联注释:

z := x % 2  // Get the modulus of x

您还可以使用内联注释来解释执行某些操作的原因,或者提供一些额外信息,如:

x := 8  // Initialize x with an arbitrary number

您应该只在必要时使用内联注释,并且何时可以为阅读该程序的人员提供有用的指导。

评论测试代码

除了使用注释作为文档代码的方式之外,您还可以使用开始标记( /* )和结束标记( */ )来创建块注释。 这允许您在测试或调试当前正在创建的程序时注释掉您不想执行的代码。 也就是说,当您在实现新的代码行后遇到错误时,您可能需要对其中一些代码进行评论,以确定是否可以解决确切的问题。

使用/**/标记还可以让您在确定如何设置代码时尝试其他选择。 在继续处理代码的其他部分时,您还可以使用块注释来注释掉失败的代码。

multiply.go
// Function to add two numbersfunc addTwoNumbers(x, y int) int {    sum := x + y    return sum}// Function to multiply two numbersfunc multiplyTwoNumbers(x, y int) int {    product := x * y    return product}func main() {    /*        In this example, we're commenting out the addTwoNumbers        function because it is failing, therefore preventing it from executing.        Only the multiplyTwoNumbers function will run        a := addTwoNumbers(3, 5)        fmt.Println(a)    */    m := multiplyTwoNumbers(5, 9)    fmt.Println(m)}

注意 :注释掉代码只能用于测试目的。 不要在最终程序中留下注释掉的代码片段。

使用/**/标签注释掉代码可以让您尝试不同的编程方法,并通过系统地注释和运行程序的各个部分来帮助您找到错误的来源。

结论

在Go程序中使用注释有助于使您的程序对人类更具可读性,包括您未来的自我。 添加相关且有用的适当注释可以使其他人更容易在编程项目上与您协作,并使代码的价值更加明显。

在Go中正确评论您的代码也将允许您使用Godoc工具。 Godoc是一个工具,它将从您的代码中提取注释并为您的Go程序生成文档。

赞(0) 打赏
未经允许不得转载:老赵部落 » 如何在Go中写评论

评论 抢沙发