Skip to content

Commit

Permalink
Add a section about string quoting
Browse files Browse the repository at this point in the history
  • Loading branch information
zas committed Sep 21, 2023
1 parent 377f083 commit 5db5f74
Showing 1 changed file with 43 additions and 0 deletions.
43 changes: 43 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,49 @@ We use snake-case to name all functions and variables except for the pre-generat

`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

0 comments on commit 5db5f74

Please sign in to comment.