docs: update best coding practices with typescript lessons learned (#…

…4331)

docs/code/best_practices.md

@@ -27,3 +27,38 @@ TODO: Add more notes about how to isolate subsystems from component specifics
 *  Use `requestAnimationFrame`
 *  Avoid constant synchronous DOM reads/writes
 *  Reduce the number of composite layers
+
+### Typescript
+
+#### Definite assignment operator
+* MDC Web has other lifecycle methods (`initialize()` and `initSyncWithDom()`) that are not contained within the `constructor`.
+* Typescript compiler cannot infer that the other methods are run in conjunction, and will throw an error on properties not defined.
+* Feel free to use the `!` when you run into the error `<PROPERTY_NAME> has no initializer and is not definitely assigned in the constructor.`. ie.
+
+```
+private progress_!: number; // Assigned in init
+
+init() {
+  this.progress_ = 0;
+}
+```
+
+#### type vs. interface
+* Prefer `interface` over `type` for defining types when possible.
+
+#### any vs. unknown vs. {}
+* Defer to using `unknown` over both `any` and `{}` types.
+
+* If you must choose between `any` and `{}` defer to `{}`.
+
+#### Events
+* `@material/base` defines convenience types (`EventType` and `SpecificEventListener`) for working with events and event listeners.
+* Prefer to type as `EventType` over `string` when you expect that the string will be a standard event name (e.g. `click`, `keydown`).
+* Prefer to type as `SpecificEventListener` over `EventListener` when you know what type of event is being listened for (e.g. `SpecificEventHandler<'click'>`).
+
+#### When to use Node/Element/HTMLElement
+* `Node` is more generic than `Element`, while `Element` is more generic than `HTMLElement`.
+* `Node` is mainly used for the document or comments/text.
+* `Element` should be used when the type in question could be `HTMLElement`, `SVGElement`, or others.
+* `HTMLElement` only pertains to DOM Elements such as `<a>`, `<li>`, `<div>` just to name a few.
+* Use the most generic type that you think is possible during runtime.