What's the convention for code lines with comments?

Question

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?

Marrissa

Usually, comment lines are preferred above the commented portion of code. Be aware, however, that comment blocks right before package, type and func declarations will show up in godoc. For license headers, leave a blank line between the header and the package godoc comment. – Lubeck

Seems like if your line is longer than a certain number of characters it will be indented to the right, otherwise it's appended right after the line... – Wappes

Highly recommended official blog post: Godoc: documenting Go code – Acanthopterygian

Answer 1

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)

Anissa

Thank you. Although this is clearly not the correct forum, just for the record I think your second case obscures, rather than enhances, the understandability of the code. (:-) – Marrissa

@Marrissa that is the whole point of go fmt. What you think is going to be different than what the next person thinks. With a canonical style we don't need to worry about it any more and can focus our attention on things that matter more. – Cacogenics

@Cacogenics Accepted; but if the convention, for example, is to discourage same-line comments, then perhaps gofmt would do better by splitting them onto a new, preceding line. I also think code readability is probably one of the things that matter most, although, of course, readability is subjective. And, although we should definitely all adhere to standards, I think we should 'worry' about making them as good, and as fit-for-purpose, as possible. – Marrissa

Can't argue there. FWIW, I don't think same line comments are discouraged, I just think your case of describing function args on separate lines was not optimized for. Same line comments look fine otherwise: play.golang.org/p/JNpGqSD9Dz – Cacogenics