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 ( +