The Holocron

Golden Rule

Enforce these, or your own, agreed upon guidelines at all times. Small or large, call out what's incorrect. For additions or contributions to this Code Guide, please open an issue on GitHub. When in doubt or not explicity specified, use existing common patterns.

Part of being a good steward to a successful project is realizing that writing code for yourself is a Bad Idea™. If thousands of people are using your code, then write your code for maximum clarity, not your personal preference of how to get clever within the spec.

- Idan Gazit

General Preferences

• Don't try to prematurely optimize your code; keep it readable and understandable.
• Well commented code is extremely important. Even if you think the code is self-describing, its often better to not leave others guessing as to the purpose of uncommon or non-obvious code.
• Take time to describe components, how they work, their limitations, and the way they are constructed.

Editor preferences

Set your editor to the following settings to avoid common code inconsistencies and dirty diffs:

• Use tabs set to four spaces.
• Trim trailing white space on save.
• Set encoding to UTF-8.
• Add new line at end of files.

Tip: Document and apply these preferences to your project's .editorconfig file. For an example, see the one in this repo. Learn more about EditorConfig.

Whitespace

Only one style should exist across the entire source of your code base. Always be consistent in your use of whitespace as it helps improve readability.

Tip: configure your editor to "show invisibles". This will allow you to eliminate end of line whitespace, eliminate unintended blank line whitespace, and avoid polluting commits.

Commenting Code

Commenting code is an important and effective tool for communicating deeper what can't always be said with code. I've found that Sarah Drasner's article on The Art of Comments details the best way to comment code.

Code can describe how, but it cannot explain why.

Consider a few things when writing code and attempting to decide whether or not it deserves some comments:

1. Future you doesn't always remember why present you decided to write something a particular way. Code styles change, support requirements change, and sometimes what was seemed clear and legible at the time is not always by everyone else.
2. Not everyone comes from the same backgrounds nor experiences. Don't assume that because you understand it, everyone on the team will. That doesn't make them less smart, but maybe makes your solution a bit more creative. Explain the why so everyone can learn.
3. Comments allow one to break up code into smaller readable chapters of code. Smaller sections of code provide a developer with easier and more manageable chunks to read through.
4. Sometimes deadlines come up faster than expected; leaving comments can provide a roadmap for what was done given the divergence from what was intended.
5. Did you take a snippet from another site? Or did you copy a solution from StackOverlow? No problem. Write a comment to leave a paper trail for others to follow or to credit the source.
6. If there is an open discussion on GitHub or StackOverflow about the code or approach you're using, include the link in your comment.

Tip: Keep your README.md updated as a project evolves.

Choosing Dependencies

Consider a few things when choosing dependencies:

• Audit your packages on a regular basis to see if they have become unused or irrelevant in order to keep down your bundle size. Use a tool like depcheck or npm outdated to check the registry to see if any (or, specific) installed packages are currently outdated.
• Before using a dependency, check its download statistics and a mature version release frequency with a large number of maintainers to see if it is heavily used by the community. More usage mostly means more contributors, which usually means better maintenance, and all of these result in quickly discovered bugs and quickly developed fixes. Use npm-stat.
• Having loads of contributors won't be as effective if maintainers don't merge fixes and patches quickly enough. Use npm view
• Always make sure your code works with the latest version of its dependencies without breaking, before commiting back.
• Dependency updates sometimes contain breaking changes. Always check their release notes when updates show up. Update your dependencies one by one, that makes troubleshooting easier if anything goes wrong. Use a tool such as npm-check-updates.
• Check to see if the package has known security vulnerabilities. Use something like Snyk.
• Make sure you use resources that you have the rights to use. If you use libraries, remember to look for MIT, Apache or BSD but if you modify them, then take a look at the license details. Copyrighted images and videos may cause legal problems.