search

nushell / nushell.github.io

Nushell's main website, blog, book, and more
https://www.nushell.sh/book/
MIT License
183 stars 426 forks source link

Question: Style guide wording choice (RFC 2119?) #1604

Open NotTheDr01ds opened 2 hours ago

NotTheDr01ds commented 2 hours ago

tl;dr Are there any objections to using RFC 2119 style for the Style Guide (e.g., "SHOULD", "SHOULD NOT", etc.)?

The Style Guide currently a somewhat "awkward" (IMHO) phrasing for most recommendations. E.g.:

It's recommended to put one space after : after record key.

That could be more naturally expressed with:

It is recommended that you put one space after : after record key.

or, better:

A single space after the : following a record key IS RECOMMENDED.

But most readable and natural is the RFC 2119 style:

The : after a record key name SHOULD be followed by a space.

I know (because I share it) that there's often resistance to using RFC 2119 wording, and it's often not needed. However, I think that it makes this particular document much more readable.

NotTheDr01ds commented 2 hours ago

Side-note: SHOULD (instead of MUST) since these are recommendations currently.