From 5db5f74cda30e091236383e5f17f258383efbd0e Mon Sep 17 00:00:00 2001
From: Laurent Monin <github@norz.org>
Date: Thu, 21 Sep 2023 21:30:58 +0200
Subject: [PATCH] Add a section about string quoting

---
 CONTRIBUTING.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f8769543d5..3254150b13 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -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.
+We use single quotes for identifiers and keys (those are unlikely to contain a single quote; and usually no special character or space).
+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.
+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.
+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