Skip to content
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.

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

Add a section about string quoting to CONTRIBUTING #2322

Merged
merged 1 commit into from
Sep 21, 2023
Merged
Changes from all commits
Commits
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
43 changes: 43 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,49 @@

`gettext` and `gettext-noop` have been built-in the Picard code as `_` and `N_` respectively to provide support for internationalization/localization. You can use them without imports across all of Picard code. Make sure to mark all displayable strings for translation using `_` or `N_` as applicable. You can read more about python-gettext [here](https://docs.python.org/2/library/gettext.html).

### Strings quoting: single or double quotes?

As a general guideline, we tend to use double quotes for translatable strings and/or English phrases; or anything that may contain one or more single quotes.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 157 Warning

Expected: 80; Actual: 157
We use single quotes for identifiers and keys (those are unlikely to contain a single quote; and usually no special character or space).

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 136 Warning

Expected: 80; Actual: 136
Of course, it all depends on context and those are just hints, rather than rules.

Examples:

```python
print("It is red")
```

Because changing it to `print("It's red")` would not require changing quotes.

```python
d = dict()
d['key'] = "It's red"

if 'key' in d:
print(_("The value for 'key' is {key}.").format(**d))

```

In above example, 'key' is an identifier, usually using characters from `[a-z0-9_]` set.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 88 Warning

Expected: 80; Actual: 88
But the printed string is translatable (English phrase).

```python
l1 = ['big', 'small']
l2 = ["It's a big city", "Small is the village"]
l3 = ["The city is big", "That's a small village"]

d = {
'big': "The City",
'small': "The Village",
}
print(d['small'])
```

In above example, `l1` contains identifiers (keys of dict `d`) while others are English words/phrases.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 102 Warning

Expected: 80; Actual: 102
In the dict declaration, keys are single-quoted but values are double-quoted.

Otherwise, choose whichever limit the number of escaped characters.


## Git Work-flow

Expand Down
Loading