[mentalgear]

Keep the reasoning as close to the code as possible.

1. Code should be self-explanatory, so should vars, function names and the entire shape be.

2. For the remaining non-obvious bigger design decisions, add a comment header (eg jsdoc) above the main section code block, and possibly refactor it out into its own file. Prefer to have a large comment header (and possibly some inline comments) outlining an important architectural part than having that knowledge dissipate with time, separate external docs and your leaving workers.