Comments

[nrc]

As well as specifying formatting for comments, we should decide on how much we expect Rustfmt to enforce (at the least, it cannot enforce correct grammar). My experience has been that re-formatting comments is almost impossible to get right. However, it is possible that we might be able formulate acceptable heuristics if we want to go down that road.

This one will need some fleshing out, but to start with:

• Prefer // comments to /* ... */ comments, use the latter only where there is code following on the same line.
• Prefer /// for doc comments, use //! only for module/crate-level docs. Avoid the other forms.
• Comments should be complete sentences. Start with a capital letter, (usually) end with a period (.).
• Have a single space after the comment sigils: // A comment. or /// A doc comment.
• Comments should be indented with the code they are 'attached' to.
• Comments should be kept within the 80 char margin (longer comments are harder to read).

I do not believe we should get into what makes a comment good or bad, beyond its formatting.

I propose that Rustfmt should basically avoid formatting comments. It can move comments to make them aligned with code and can add or remove whitespace around comments (if necessary, and I suspect it won't be). But Rustfmt should not change the actual text of the comment at all. Rustfmt should warn if a comment runs over the maximum width, but shouldn't attempt to fix that. Rustfmt should not change the style of the comment, nor the whitespace inside a comment.

I'd be happy to have more sophisticated comment formatting (word-wrapping, etc.) behind an option, if that is of interest to users.

[Mark-Simulacrum]

Adding something about avoiding the ///////////////////////// style comment "header" and/or suggestion as to how rustfmt should deal with them. I know one of the recent re-format PRs to rustc had a problem with it reformatting a // section to /// because of such a block.

[strega-nil]

I think we should use // for line comments, and /* */ for longer comments. Unlike C/C++/lots, we don't have the confusing issue with closing tags, and they're better for accessibility (cc @camlorn). Similarly, doc comments should almost always use the /** form.

Something like the following would be my preferred solution:

/*! Module comment
    this is the documentation for a module
*/

/** Ooh, check out this type. It's so nice and typey.
    It's an example struct, wee!
*/
struct Type;

fn main() {
    /*  This is the main function
        it's nice, I guess
    */

    // oh nice, line comment! adding together stuff!
    println!("{}", !1 - !2);
}

[alexcrichton]

Rustfmt should warn if a comment runs over the maximum width

I'd personally be wary of adding warnings for this, sometimes the reason a comment is long is hard to fix (e.g. a long url). If rustfmt always emitted a warning for this unconditionally it may be annoying to turn off the warning on a case-by-case basis.

[nrc]

My reasoning for always using line comments:

• internal consistency - better to have one kind of comment than two
• external consistency - most [citation needed] C/C++ code guides mandate line comments
• less ambiguity - what is a long comment vs a short comment
• tooling - at least in the editors I use, it is easier to format a block with line comments than block comments. Also some editors don't handle nested block comments as well as the language does.

[nrc]

@alexcrichton does make tidy have a solution for this?

I could imagine allowing some kind of rustfmt::skip directive inside comments, although that might be more annoying than the warnings

[alexcrichton]

@nrc for make tidy we've got // ignore-tidy-linelength. I think that means that if the string "ignore-tidy-linelength" shows up anywhere in the file that the whole file is ignored for line lengths.

It's true though that the only reason I've ever seen at least to have a super long line is for literally URLs, so maybe there could just be an exception where if the line of the comment that's over the limit contains "http" rustfmt just conveniently doesn't warn about it

[strega-nil]

@nrc

• internal consistency - I personally don't care very much about this argument. Rust is, and always has been, very TIMTOWTDI
• external consistency - (gnu)[https://www.gnu.org/prep/standards/html_node/Comments.html#Comments] recommends block comments
• ambiguity - "anything over a line" or "anything over two lines"
• tooling - in the editor I use (vim), it's easier to format a block with block comments, because

// Foo
// Bar
// Baz

/*  Foo
    Bar
    Baz
*/

In the line comment case, if you hit >>, then it'll indent everything (including the //) to the right, as opposed to just the comment itself (this is really annoying for code blocks inside of comments, as in an example).

I don't know of any editor that, when using rust code highlighting, doesn't support nested block comments.

[skade]

I agree that rustfmt shouldn't change the comment style. It was probably picked for a reason.

I would appreciate trimming of whitespace and word wrapping a lot, though, as re-justifying comments is a real annoyance.

Some linting and spell-checking would be very cool :).

[pnkfelix]

The current bug description does not address the issue that external tools may be using sigils within comments to denote certain things.

One obvious example of this is markdown, which I imagine makes it hard to detect adherence to the rules about having periods at the end of sentences. (Plus english itself makes it hard, see?)

Another example that is of particular importance to me is Tango, which uses an @ character immediately after the // comment sigils (with no intervening whitespace between the // and the @) to signal that the tool should treat this comment specially.

While I could have Tango accept (and perhaps even emit) // @ instead of //@, I would prefer if the rules in the description were relaxed to allow for an arbitrary series of non-whitespace, non-alphanumeric characters to follow the //, then a space, and then the comment text.

---

Update: I did not read the description carefully enough; I had thought it was proposing the 80 character width rule be imposed with more than a warning.

The description mentions moving comments and altering the whitespace "around" comments; I infer this is actually describing something much more constrained, namely reindenting comments, which solely, consists of modifying the amount of whitespace that falls before the // comment sigil. Is this a correct inference?

[nrc]

@skade

I would appreciate trimming of whitespace and word wrapping a lot

Unfortunately this is the hardest bit because we need to be smart enough to guess when a comment is a code block and we should preserve whitespace and when it is not and we should wrap. We could trim trailing whitespace at the least, although I seem to remember even that can be significant for some systems :-(

@pnkfelix

Yeah, the bullet points should be read as "should"s not "must"s and my current thinking is that they should not be enforced by tools. Rustfmt would have to move comments around, but that should probably be the limit of what it does.

[solson]

We could trim trailing whitespace at the least, although I seem to remember even that can be significant for some systems :-(

Even in markdown, in fact, where it inserts a break within a paragraph. :/

[joshtriplett]

@nrc For code, we could look for triple-backquoted code blocks and leave them alone.

[nrc]

@nrc For code, we could look for triple-backquoted code blocks and leave them alone.

We considered this but, a lot peoples' use cases did not fit this pattern. E.g., people temporarily commenting out code and running rustfmt on save. Or people just not using markdown for their comments (surprisingly common outside the core Rust projects).

[pnkfelix]

@nrc wrote:

Rustfmt would have to move comments around, but that should probably be the limit of what it does.

Can you confirm the inference I made when I asked earlier:

I infer this is actually describing something much more constrained, namely reindenting comments, which solely consists of modifying the amount of whitespace that falls before the // comment sigil. Is this a correct inference?