CodingGuidelines.md

Coding Guidelines

General

• These are not to be blindly followed; strive to understand these and ask
  when in doubt. Sometimes standards are a bad idea.

• Don't duplicate the functionality of a built-in library.

• Really try hard not to duplicate the functionality of any existing library or function. If this means making a new repo to share across projects... please do that... even if it's a simple function.

• Don't swallow exceptions or "fail silently."

• Don't write code that guesses at future functionality. (Don't be an architecture astronaut)

• Use callbacks, passed objects and/or split the repo up into multiple repos to prevent tight coupling across directory boundaries. Especially avoid cross-importing.

• Never use IPC where importing a class will work. If that class comes with too much baggage, break it up and import the stuff you need.

• Strive to adhere to the Unix Philosophy. There are some nice articles that discuss this philosophy as applied to object oriented code:

  • https://codeclimate.com/blog/your-objects-the-unix-way/

  • https://tommcfarlin.com/do-one-thing-and-do-it-well/

New Projects

• Master branch must require code reviews and passing tests

• All new projects must have a full CI pipeline, including linters, tests

• Coverage enforcement is required

• If a project has dependencies, it must use and commit a lockfile of some sort

Object-Oriented Design

• Avoid global variables & long parameter lists

• Limit dependencies of an object (entities an object depends on).

• Limit an object's dependents (entities that depend on an object).

• Prefer composition over inheritance.

• Prefer inheritance over callbacks and branches.

• Prefer small methods. Between one and five lines when it makes sense

• Prefer small classes with a single, well-defined responsibility. When a
  class exceeds 100 lines, it may be doing too many things.

• Tell, don't ask.

Opening files, using API's:

• Client facing systems should never hit the internet/connect to a network filesystem, open a file that might be on a network drive, etc. ... as a precondition for startup. Missing network/internet always needs to be gracefully handled.

• When opening a file or reading data from the internet in any way, assume it contains deliberately constructed malicious data. Write a test to prove that appropriate exceptions are thrown, and are gracefully handled.

• When doing IPC, assume the other service can be down. Ensure timeouts & failures are handled.

Python

• Avoid putting any real logic in del override

Javascript

• Start new projects with Typescript

• Use maps, not objects, as much as possible.

Testing

• Don't test private methods.

• Use intermediate assertions about state during test progression.

• When at all possible, put your debug logs in the test, not in the code.

• Use both integration tests and unit tests not one or the other.

• Don't evade coverage checks.

Relational Databases

• [Index foreign keys].

• Constrain most columns as [NOT NULL].

• In a SQL view, only select columns you need (i.e., no SELECT table.*).

• Use an ORDER BY clause on queries where the results will be displayed to a
  user, as queries without one may return results in a changing, arbitrary
  order.

• Never put meaningful or computed data in the "id" or "primary key" field of a table.

• Sqlite need not be considered a "relational database", depending on what you're doing with it.

  • Use as key-value store is OK

  • Use as indexed "blob storage" instead of filesystem is OK

CI/CD & Scripts

• No complex bash scripts.   Scripts that are complex enough to need stuff like functions and loops should be moved into a language suitable for complexity and testing, like python or node.

• No one-off complex scripts.  Scripts that manage deployments, requirements, etc should, ideally be abstracted and run in many projects.... rather than each project having its own requirements, versioning and deployments systems.   This is especially true for libraries.

Web

• Avoid rendering delays caused by synchronous javascript hits.

• Use HTTPS instead of HTTP when linking to assets.

• Use UTF-8 only

Security Best Practices

Yes, it's important for developers to consider security during every aspect of development. But especially when writing webites, public endpoints, storing customer data and more. Here's a quick list of some threats to consider and learn about so you can accurately review and code with security in mind:

• Open Redirect
• Insecure Direct Object References (IDOR)
• Cross-Site Scripting (XSS)
• Cross-Site Request Forgery (CSRF)
• SQL Injection
• Server-Side Request Forgery (SSRF)
• The current OWASP Top 10-changes as vulns change, check it out. It's a cool site.

Changes to this document

To add new standards:

• First make sure your proposal doesn't suck. Coding standards that suck have the following attributes:

  • Full of author's own opinions and personal coding style.

  • Huge focus on style and formatting issues

  • Recommendations disguised as standards.

  • See: https://codeahoy.com/2016/05/22/effective-coding-standards/

• Open up a slack discussion with at least 3 other devs and propose one or more additions or changes. Include the CTO and the Engineering Manager.

• Edit this page with the verbiage everyone agrees on.

This is good!