Style guide for comments

Glad to hear. Probably most of them can’t be automated (put into Clippy or tidy), but if we could a) check all the points mentioned in this thread are covered there, b) drill it into PR reviewers (and authors?) to follow them, I think that would be great.

I agree. Style guides from non-technical agencies also tend to recommend it these days, I believe. Double spaces have (rightly in my view) fallen out of favour since the decline of typewriters, although a substantial minority of people still us them it seems.

I don’t really care about most of these issues, although I do think there should be a “house style” that has rules for them, because consistency makes things easier to read.

But I do care about how wide the source code gets :slight_smile: I have middle-aged eyes, so I use a larger font than a lot of people seem to prefer, and I want to be able to have two editor windows open side by side with different pieces of code in them. This only works if comments are kept to the same overall width as the code. It is better if everything is no more than 80 columns wide. 100 is acceptable. 120 is too wide.

(It’d be okay to make an exception for extremely arcane stuff, like assembly language and TECO macros, where you may want to put a comment on every single line.)

(Middle-aged eyes also appreciate a wider space after sentence-ending punctuation, but I think that’s something the computer ought to do for me automatically, not something I ought to have to type.)

3 Likes

Just dropping this off here:

4 Likes

Nice. Plans on reviving that project? I think @centril would be a fan of that w.r.t. “in order to”. :wink:

I like those guidelines too. I think we could take that document and expand on it, perhaps.

How should we take things forward from here?

1 Like

I’d personally prefer this not to go forward, unless 1) the style check is automated and 2) the churn is one-time and is grouped together with the great rustfmt run.

1 Like

You couldn’t automate this all without strong AI probably. :stuck_out_tongue:

I personally do not get the motivation for having a style guide for comments. For documentation, it absolutely makes sense. But for comments?

Whether to follow all Latin abbreviations (such as “e.g.”, “i.e.”, and “N.B.”) with commas, per American (and possibly other) convention, or without commas, per British (and possibly other) convention.

Speaking as an American, I honestly don't care. I wouldn't bat a second glance at "i.e." missing a comma, and to be quite honest, I never even noticed that was a thing. Maybe you'd annoy an English professor or something.

On the other hand, seeing the commas outside of your quotation marks there does get to me quite a bit...

  • The desired tone (formal/informal/etc.) of language.

I hate the notion that comments should be grammatically-correct, complete sentences written in formal English. To me, there are many types of comments, and they have different desirable qualities. For instance:

  • Short comments to explain something unclear. These are a last resort alternative to refactoring the code to make it clearer. It is crucial that any comment like this must communicate its point as effectively as possible and without intimidating the reader.
  • Short comments to acknowledge or justify something unusual. For instance:
    #[allow(unused)] // rustc bug, see rust-lang/rust #45268
    use std::io::Write;
    
    #[inline(always)] // elide large stack copies
    fn dot(a: V3, b: V3) -> f64 {
        ...
    }
    
    To me, styling this as // Elide large stack copies. gives it a completely different and silly-sounding tone (changing it from what is clearly a sentence fragment into what looks like the imperative voice) that makes me want to rephrase it as // Inline to elide large stack copies., at which point the duplication of the word "inline" makes me want to just remove the comment entirely.
  • Comments explaining at a high level what the code is doing. Again, these shouldn't even have to exist as you can usually find ways to break up the code and make it more palatable. I suppose that I would in fact write these in proper English, in the imperative mood.

In the end, what matters is that comments are relevant (i.e. not stale), and that the reader feels inclined to read the ones that are important. Nitpicking their style feels like a waste of time that does not benefit anyone.

3 Likes

That's largely a US-centric writing-style idiosyncrasy. Even in the US, including commas and periods before a closing quote depends on the intended context. For example, including punctuation within a quote in US legal documents is permissible ONLY if it was included in the original text from which the text was quoted.

1 Like

my favorite style guide for comments and stuff is “whatever makes the most sense”.

(btw: putting punctuation that isn’t part of a quote inside the quote makes no sense.)

2 Likes

You'd annoy many a person, in fact. It's a contentious matter of grammar. The whole reason we have grammar is to make ourselves clearly understood to one another. This is admittedly a small matter, but consistency is important either way (I agree it doesn't matter which we choose, so long as we stick to one throughout, so as not to cause even slight confusion to readers).

I hate the notion that comments should be grammatically-correct, complete sentences written in formal English.

I must say, I find that view highly unconstructive. As I intoned above, without grammar, language would be a very poor means of communication! Yes, there's a spectrum, but the crucial point here is that we should strive to make ourselves as easy to understood to our intended audience as possible. Using informal English, especially humour, is not very helpful in a codebase, given your audience is composed of readers/coders from around the world – from different cultures, speaking different dialects of English, or not natively speaking English at all.

5 Likes

Indeed, punctuation that doesn’t relate to the quoted phrase inside of quotation marks makes no sense. Unfortunately it’s very common in the US, albeit not omnipresent. Then again, a lot of American style conventions make no sense to me. The one exception is commas after Latin abbreviations, but like I said, I don’t care much whether we do that, as long as we’re consistent throughout.

I don’t think being consistent is that important. Precisely because we come from all over the world and we don’t wanna give the impression that one dialect is more important or more correct than the others.

I completely disagree, because then the comments will be hard to read. The documentation should also serve as a model. If it’s inconsistent, it’s very unprofessional.

2 Likes

I concur. It’s not about giving “importance” to dialects. This isn’t a competition of prestige whatsoever. I’m British, and I generally prefer British English myself, but I’m happy to accept American English for a) the sake of consistency, which has the benefits mentioned above; b) it’s probably the most widely-understood/learnt form of English.

1 Like

To turn it around, one might argue good, consistent language use will make docs and comments more accessible for consumption by non-native readers, and a style guide might actually serve as a help to less experienced users of the English language to improve their writing in a way that would not be available if no style guide existed.

3 Likes

If you know any dialect of English, it’s not hard to write in American English. Reviewers can help you.

3 Likes

Good point!

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.