The topic of stylistic decisions in the source code for rustc recently arose after a a large PR of cosmetic and other minor changes that I made. Although I argue I made a lot of the comments more readable and consistently styled/formatted, the point was fairly brought up that others may have different views, explicitly or implicitly, and the codebase may soon drift away from a convention again, without specific guidelines, and their enforcement in PR reviews. Hence, I was hoping to garner the feedback of other rustc devs here, and in particular the compiler and documentation teams. (Is there any way to tag them here?)
Some things I think we need to decide:
- Whether to enclose all code in comments in backticks.
- Whether to enclose metavariables in comments in backticks.
- At what line length to wrap comments, and whether this should be relative to the start of the comment or column 0.
- 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.
- Whether to use American English spelling throughout.
- Capitalisation rules. For example, whether to start all sentences and phrases with capitals, or just phrases (that is, no verbs).
- Whether to follow full stops with one or two spaces.
- Whether to use abbreviations for common words or not.
- Use of punctuation in general.
- The desired tone (formal/informal/etc.) of language.
- The style (and Markdown structure) for file/module headers.
- Whether (or in which cases) to allow end-of-line comments.
- When to prefer documentation comments (
///) and when to prefer regular comments (
- The use of indented vs. backtick-enclosed code blocks.
- The use of double-hyphen (
--) for the dash.
- The use of dashes versus colons versus semicolons vs commas.
- Style/formatting of
Things that probably aren’t important:
- Whether to use the Oxford comma.
- Humour in comments.
Good, well-written, and well-formatted comments are important to maintaining a clean codebase, in my view. I’ve seen a large variation in the quality and amount of comments in rustc, but going forwards, we should at least be aiming for consistency. All thoughts and opinions welcome.
N.B., so as not to bias replies either way, I’m withholding my own views for now!