gofmt commenting suggestion
Petar Maymounkov
I'd like to suggest a comment formatting rule.
In strict style environments (like inside Google when programming C++)
one uses VIM's "gq" sequence to justify all comments to go no farther
than
the 80 column limit and to fill the space from the initial "//" to the
80-column
mark tightly on every line.
Since Go style is generally not pre-ocuppied with fitting in exactly
80 columns,
in my experience the following rule is very helpful:
Given a multi-line comment, justify it so that each line is no more
than 80 characters,
counted from the starting "//" (open-comment) position.
I think that 80-letter comments are the perfect reading length. But
unlike in C++ strict
style, here we want them to count from the starting offset of the
comment, not
from the 0-column.
VIM cannot do this rule currently, at least not without extra coding.
But I think it would be
great for Go.
What I do currently is to use the "gq" on vim, but this has the
unpleasant effect that
more indented comments have to be shorted in length, which looks ugly
and non-uniform.
Comments?
--Petar
Russ Cox
I much prefer to see text in which line breaks happen,
when possible, at punctuation boundaries,
making the text easier for people to scan.
Compare the doc for io.Writer:
// Write writes len(p) bytes from p to the underlying data stream.
// It returns the number of bytes written from p (0 <= n <= len(p))
// and any error encountered that caused the write to stop early.
// Write must return a non-nil error if it returns n < len(p).
with the 80-character wrapped version:
// Write writes len(p) bytes from p to the underlying data stream. It
returns the
// number of bytes written from p (0 <= n <= len(p)) and any error
encountered that
// caused the write to stop early. Write must return a non-nil error
if it returns
// n < len(p).
I find the first version far easier to read quickly.
This seems to be a place where it would be very hard for a
program to do a good enough job.
Russ
Petar Maymounkov
P