Skip to content

Ask folks to use the Oxford comma in diagnostics #2093

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 5, 2024
Merged

Ask folks to use the Oxford comma in diagnostics #2093

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/diagnostics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,8 @@ use an error-level lint instead of a fixed error.
compiler messages are an important learning tool.
- When talking about the compiler, call it `the compiler`, not `Rust` or
`rustc`.
- Use the [Oxford comma](https://en.wikipedia.org/wiki/Serial_comma) when
writing lists of items.
Comment on lines +159 to +160
Copy link
Member

@jieyouxu jieyouxu Nov 4, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: I don't think we want to make this advice because just like what the wikipedia entry says

The serial comma can serve to avoid ambiguity in specific contexts, though its employment may also generate ambiguity under certain circumstances.

I think it's context-dependent and is best left to the reviewer/author's judgement for whether or not to deploy oxford commas.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have rarely seen it add ambiguity, and have far more seen it's lack add ambiguity

Copy link
Contributor Author

@onkoe onkoe Nov 4, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the review! It's a good call to think a bit before writing diagnostics. However, I intentionally qualified it with "when listing items".

The ambiguities stemming from the extra comma are pretty rare. When they do appear, it's typically because the author was doing more than listing items.

With that in mind, do you think softer wording would be more effective? My goal was to avoid ambiguity in the diagnostic formatting rules.

Copy link
Member

@jieyouxu jieyouxu Nov 4, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have too strong of an opinion on this, so if tshepang is in favor then we can merge and see if this advice turns out to not always apply in practice (I suspect rarely). We can always adjust this advice from more experience.


### Lint naming

Expand Down