style-guide: add file extension instructions #19776
Conversation
Managor
requested review from
kbdharun,
sbrl and
sebastiaanspeck
as code owners
github-actions
bot
added
the
documentation
Totally agreed.
I had actually started working on precisely that change :) hopefully I can submit it after this change gets in. |
contributing-guides/style-guide.md
Outdated
|
|
||
| Whereas for Powershell, prepend the environment variable with a dollar sign, Env and a colon, then enclose it with backticks (`$Env:VARIABLE_NAME`). For example: "Manage the `$Env:JAVA_HOME` environment variable". | ||
|
|
||
| When describing file formats, either use the brand name like JSON, or prepend the file extensions with a dot like `.warts`. |
There was a problem hiding this comment.
The "warts" example might be a little obscure. What about using an example that's both more well-known as a file extension, and looks more like a brand name in plain text?
| When describing file formats, either use the brand name like JSON, or prepend the file extensions with a dot like `.warts`. | |
| When describing file formats, either use the brand name like JavaScript, or use a file extension with a dot like `.js`. |
There was a problem hiding this comment.
It's not written anywhere, but we tend to always prefer brand names over technical terms. Having these be the same would go against that.
I chose .warts only because I like to use examples where the guideline was discovered. We can change that to something else.
There was a problem hiding this comment.
we tend to always prefer brand names over technical terms. Having these be the same would go against that.
I'm not sure I follow. Are you saying that the guideline you're adding currently says "Do X or Y", but you think it should imply "...but preferably X"?
It's not written anywhere
Indeed, why not just say it explicitly, then? I don't think having Y refer to a different entity than X implies that we have a preference for X's form.
3 participants
The Special Cases category is starting to feel a bit bloated. If anyone wants, they can take similar instructions and put them under their own category.