@@ -10,7 +10,75 @@ Do not install any new dependencies.
1010# Testing
1111
1212Run ` npm test ` to test everything. This runs the build, checks code formatting,
13- and finally runs unit tests.
13+ and finally runs unit tests. Never run any other test command than ` npm test ` .
1414
1515When writing new tests, always follow the format in ` html.test.js ` as a
1616reference, using ` describe ` and ` it ` functions to describe unit tests.
17+
18+ # Best Practices
19+
20+ - Don't constantly re-create RegExp objects, put them in a variable outside of
21+ functions so they are only created once (f.e. at the top level scope of the
22+ module).
23+ - Always aim for the simplest _ readable, understandable_ solution.
24+ - If you're adding too much code, you might be solving the problem in a too complex way.
25+ - Put re-usable code in functions, always avoid duplication.
26+ - Don't use complex one-liners or clever bit fiddling unless it is absolutely
27+ necessary for something like solving a performance _ problem_ , prefer multiple
28+ simple readable lines.
29+ - Don't prematurely optimize, always prefer readable code first.
30+ - Document your code with JSDoc comments. All functions, methods, and classes
31+ should have JSDoc comments.
32+ - Avoid unnecessary braces. For example for conditional or loop blocks with a single statement, prefer:
33+ ``` js
34+ if (condition) doSomething ()
35+ ```
36+ instead of:
37+ ``` js
38+ if (condition) {
39+ doSomething ()
40+ }
41+ ```
42+ Similar with for loops, while loops, arrow functions.
43+ - Use new features such as optional chaining (` obj?.prop ` ), nullish coalescing
44+ (` value ?? defaultValue ` ), and logical assignment operators (` x ||= y ` , ` x &&= y ` ,
45+ ` x ??= y ` ) when they make the code simpler and more readable.
46+ - Always prefer ` const ` for variables that don't change, and ` let ` only for
47+ variables that change. Never use ` var ` unless absolutely necessary for special
48+ hoisting reasons.
49+ - Always prefer for-of over items.forEach
50+ - Always prefer ` element.remove() ` instead of ` element.parentNode.removeChild(element) ` .
51+ - Always prefer ` parentElement.append(childElement) ` instead of
52+ ` parentElement.appendChild(childElement) ` .
53+ - Always prefer ` parentElement.append(...childElements) ` instead of
54+ ` childElements.forEach(child => parentElement.appendChild(child)) ` .
55+ - Always prefer ` parentElement.prepend(childElement) ` instead of
56+ ` parentElement.insertBefore(childElement, parentElement.firstChild) ` .
57+ - Always prefer ` element.replaceWith(newElement) ` instead of
58+ ` element.parentNode.replaceChild(newElement, element) ` .
59+
60+ # AI only:
61+
62+ ## Never do the following:
63+
64+ - Never create tests in files that you run with ` node ` . Our code is for
65+ browsers, so always run tests using ` npm test ` which ensures our tests run in a
66+ headless browser. The output is logged back to terminal.
67+
68+ ## Responding to prompts
69+
70+ After every prompt, always provide at least three proposals for a solution, with
71+ pros and cons, and stop to allow the user to select the desired direction.
72+
73+ A conversation should be like this:
74+
75+ 1 . User: Let's do [ thing to do] .
76+ 2 . AI: Here are three ways we could do X:
77+ 1 . Do it this way because of A, B, C. Pros: ... Cons: ...
78+ 2 . Do it that way because of D, E, F. Pros: ... Cons: ...
79+ 3 . Do it another way because of G, H, I. Pros: ... Cons: ...
80+ 3 . User: Let's go with option 2.
81+ 4 . AI: Great! (AI goes and implements option 2)
82+ 5 . Repeat from step 1.
83+
84+ Basically, _ always_ confirm with three proposals before implementing anything.
0 commit comments