Style guide for comments

[alexreg]

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

[ExpHP]

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.

[Tom-Phinney]

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

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.

[Soni]

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.)

[alexreg]

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.

[alexreg]

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.

[Soni]

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.

[TimDiekmann]

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.

[alexreg]

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.

[djc]

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.

[alexreg]

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

[alexreg]

Good point!

[system]

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