代码行中的注释通常遵循以下约定:

huangapple go评论72阅读模式
英文:

What's the convention for code lines with comments?

问题

代码格式化约定的Go模型是“gofmt 就是约定”。其中一个约定的部分让我难以理解,希望能有一个正式的定义,说明gofmt是一种实现,而不是通过实例来推断模型。这是一个示例。

go fmt之前:

func sieve(mine int,                  // This instance's own prime
           inch chan int,             // Input channel from lower primes
           done chan int,             // Channel for signalling shutdown
           count int) {               // Number of primes - counter
    start := true                     // First-number switch
    ouch := make(chan int)            // Output channel, this instance
    fmt.Printf("%v ", mine)           // Print this instance's prime

go fmt之后:

func sieve(mine int, // This instance's own prime
    inch chan int, // Input channel from lower primes
    done chan int, // Channel for signalling shutdown
    count int) { // Number of primes - counter
    start := true                                 // First-number switch
    ouch := make(chan int)                        // Output channel, this instance
    fmt.Printf("%v ", mine)                       // Print this instance's prime

有人可以帮助我理解这里发生了什么吗?也就是说,为什么有些注释被压缩了,而其他的扩展了?有一些理论:

  • 这太丑陋了,这意味着优先选择没有与同一行的代码的注释
  • gofmt中有一个错误
  • 不完整(在某种程度上)的行与完整的行处理方式不同
  • 其他原因?
英文:

The Go model of code formatting conventions is "gofmt is the convention". There is one part of that convention I'm having difficulty in understanding, and it would be great to have a formal definition of which gofmt is an implementation, rather than having to deduce the model from empirical examples. Here's a sample.

Before go fmt:

func sieve(mine int,                  // This instance's own prime
	       inch chan int,             // Input channel from lower primes
	       done chan int,             // Channel for signalling shutdown
	       count int) {               // Number of primes - counter
	start := true                     // First-number switch
	ouch := make(chan int)            // Output channel, this instance
	fmt.Printf("%v ", mine)           // Print this instance's prime

After go fmt:

func sieve(mine int, // This instance's own prime
	inch chan int, // Input channel from lower primes
	done chan int, // Channel for signalling shutdown
	count int) { // Number of primes - counter
	start := true                                 // First-number switch
	ouch := make(chan int)                        // Output channel, this instance
	fmt.Printf("%v ", mine)                       // Print this instance's prime

Can anyone help me understand what's going on here? That is, why have some comments been detrimentally compressed, and others expanded? Some theories:

  • This is so ugly it must mean that code without comments on the same line is preferred
  • There's a bug in gofmt
  • Incomplete (in some way) lines are treated differently from complete one
  • Something else?

答案1

得分: 6

传统上,函数/方法的文档中描述了参数。以math/big.(*Int).Exp文档为例:

// Exp设置z = x**y mod |m|(即忽略m的符号),并返回z。
// 如果y <= 0,则结果为1 mod |m|;如果m == nil或m == 0,则z = x**y。
// 参见Knuth的第2卷第4.6.3节。
func (z *Int) Exp(x, y, m *Int) *Int {

主要注释解释了xym是什么,以及它们之间的关系。这里是godoc渲染后的效果。

对于代码也是一样,每一行通常都有自己的注释行:

// 第一个数字开关。
start := true
// 输出通道,此实例。
ouch := make(chan int)
// 打印此实例的素数。
fmt.Printf("%v ", mine)
英文:

Conventionally, arguments are described in the function/method documentation. Consider math/big.(*Int).Exp docs:

// Exp sets z = x**y mod |m| (i.e. the sign of m is ignored), and returns z.
// If y &lt;= 0, the result is 1 mod |m|; if m == nil or m == 0, z = x**y.
// See Knuth, volume 2, section 4.6.3.
func (z *Int) Exp(x, y, m *Int) *Int {

The main comment explains what x, y and m are and the relationships between them. This is how it looks rendered by godoc.

Same for code, each line usually has its own comment line:

// First-number switch.
start := true
// Output channel, this instance.
ouch := make(chan int)
// Print this instance&#39;s prime.
fmt.Printf(&quot;%v &quot;, mine)

huangapple
  • 本文由 发表于 2016年2月4日 20:47:56
  • 转载请务必保留本文链接:https://go.coder-hub.com/35201446.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定