From 797722a099bd6673ea4330ea8fb5bc26a9cce266 Mon Sep 17 00:00:00 2001
From: Randell Dawson <rdawson@onepathtech.com>
Date: Thu, 17 Sep 2020 15:05:37 -0700
Subject: [PATCH] fix: add seed code comment rules

---
 docs/how-to-work-on-coding-challenges.md | 77 +++++++++++++++++++++++-
 1 file changed, 75 insertions(+), 2 deletions(-)

diff --git a/docs/how-to-work-on-coding-challenges.md b/docs/how-to-work-on-coding-challenges.md
index 1c6faf0300..6a159c0bee 100644
--- a/docs/how-to-work-on-coding-challenges.md
+++ b/docs/how-to-work-on-coding-challenges.md
@@ -254,9 +254,82 @@ Here are specific formatting guidelines for the challenge seed code:
 - Use two spaces to indent
 - JavaScript statements end with a semicolon
 - Use double quotes where applicable
-- Comments made should have a space between the comment characters and the comment themselves
 
-  `// Fix this line`
+### Seed code comments
+
+We have a [comment dictionary](/curriculum/dictionaries/english/comments.js) that contains the only comments that can be used within the seed code. The exact case and spacing of the dictionary comment must be used. The comment dictionary should not be expanded without prior discussion with the dev-team.
+
+Comments used should have a space between the comment characters and the comment themselves.  In general comments should be used sparingly. Always consider rewriting a challenge's description or instructions if it could avoid using a seed code comment.
+
+Example of valid single line JavaScript comment:
+
+```js
+// Only change code below this line
+```
+
+Example of a valid CSS comment:
+
+```js
+/* Only change code above this line */
+```
+
+If a challenge only has a single place where code changes are needed, please use the comments in the following example to instruct the user where changes should be made.
+
+```js
+var a = 3;
+var b = 17;
+var c = 12;
+
+// Only change code below this line
+a = a + 12;
+b = 9 + b;
+c = c + 7;
+```
+
+If a challenge has multiple places where the user is expected to change code (i.e. the React challenges)
+
+```jsx
+class MyComponent extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      text: "Hello"
+    };
+    // Change code below this line
+
+    // Change code above this line
+  }
+  handleClick() {
+    this.setState({
+      text: "You clicked!"
+    });
+  }
+  render() {
+    return (
+      <div>
+        { /* Change code below this line */ }
+        <button>Click Me</button>
+        { /* Change code above this line */ }
+        <h1>{this.state.text}</h1>
+      </div>
+    );
+  }
+};
+```
+
+### Translation of seed code comments
+
+There are separate comment dictionaries for each language. The [English vesion of the comment dictionary](/curriculum/dictionaries/english/comments.js) is the basis for the translations found in the corresponding non-English versions of the files. The non-English version of the Chinese comment dictionary would be located at `/curriculum/dictionaries/chinese/comments.js`.  Each dictionary consists of an array of objects with a unique `id` property and a `text` property.  Only the `text` should be modified to encompass the translation of the corresponding English comment.
+
+Some comments may contain a word/phrase that should not be translated. For example, variable names or proper library names like "React" should not be translated.  See the comment below as an example. The word `myGlobal` should not be translated.  
+
+```text
+Declare the myGlobal variable below this line
+```
+
+>[!NOTE]
+>
+> We are working on an integration to make it possible to work on i18n for the comment dictionary. 
 
 ## Hints and Solutions