GoogleCloudPlatform / GoogleCloudPlatform/samples-style-guide
Proposal: Define pronoun prefixes for placeholder parameters
- Dominant language
- HTML
- Stars
- 13
- Forks
- 17
- PR merge metrics
- No merged PRs in 30d
Description
### Description
I couldn't find any guidance in the [samples-style-guide](https://googlecloudplatform.github.io/samples-style-guide/) or an Open Issue, about whether to use the pronoun prefix `my_`, `your_` or None in samples placeholder parameters.
I found public resources such as [Google developers - Second person and first person](https://developers.google.com/style/person) and [Material Design - Style Guide - Word Choice](https://m3.material.io/foundations/content-design/style-guide/word-choice), recommending the usage of `you` and `your` instead.
@glasnt has pointed to [https://developers.google.com/style/placeholders#placeholder-text](https://developers.google.com/style/placeholders#placeholder-text) which states `When documenting an API [...] Don't include possessive adjectives in placeholders.`
[style/code-samples](https://developers.google.com/style/code-samples) doesn't specify a requirement, although it shows this example:
```yaml
image: IMAGE_URL
```
### Proposal summary
1. Define a recommended or required style. For example: `MY_`, `YOUR_` or None.
2. Add an example, e.g. in [samples-style-guide/#pattern](https://googlecloudplatform.github.io/samples-style-guide/#pattern)
### Impact
This leads to inconsistencies across the repo, which is bad practice from a User Experience (UX) perspective.
For example on Python:
[dataplex/snippets/get_entry.py#L57](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/46a0c737defcabda799c38c348bf5c62a9b84f0d/dataplex/snippets/get_entry.py#L57)
```
project_id = "MY_PROJECT_ID"
```
[iap/example_gce_backend.py#L22](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/46a0c737defcabda799c38c348bf5c62a9b84f0d/iap/example_gce_backend.py#L22)
```
CLOUD_PROJECT_ID = "YOUR_PROJECT_ID"
```
### Challenge
- Training for sample creators, maintainers and reviewers will be required.
- It might require to batch update the style across all the samples in different repos, to be enforced.
Contributor guide
Assessment
This issue has not been assessed yet.