英文:
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 {
主要注释解释了x
、y
和m
是什么,以及它们之间的关系。这里是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 <= 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's prime.
fmt.Printf("%v ", mine)
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库,让每个人都能够通过互相帮助和分享经验来进步。
评论