# Coding Guidelines

# Summary

This section of the documentation defines some of the procedures we follow when writing code. In terms of the coding lifecycle, please see the dedicated page

# General Guidelines

The following is a list of basic rules a developer should follow when implementing any code:

• Plan and think about what you are going to code before jumping straight in. Is there already code that covers what you are going to do? What is the simplest way to code the feature without compromising maintainability?
• Write automated tests before you start coding. This allows you to explore the interface for the entire solution, forcing you to consider architecture in advance.
• Documentation is important and underrated; unless something can be written down in clear and concise words, it doesn't really make sense. Whether before or after writing the tests, add to the documentation, either to these tech docs or in the project README.
• When building an API service, there should always be a version prefix (e.g. /api/v1/users/profile) using v1 up until the point of initial rollout, then incrementing the version for each route as it changes.
• For any project which exposes itself as a web service, create and keep up to date an OpenAPI Specification file in the form of openapi.yaml in the project root.

# JavaScript / Node based projects

# Packages

• DateTime date-fns - Date utility library
• General lodash - General purpose utilities. Include via individual packages available on npm
• HTTP Axios - Promise based HTTP client
• Logging Winston - Configurable logging interface. Don't forget to install appropriate transports as defined in backend / frontend

# Styling

JavaScript projects largely have their style guidelines based around the Airbnb ruleset which your IDE should pickup and adopt automatically. In the event you are creating a new project, use this gist copying either the backend or frontend lint rules to .eslintc.js in the root of your project accordingly.

# Frontend Guidelines

Our chosen stack for building frontend projects is currently to use Vue.js. Furthermore, we have an existing component library (which will soon be abstracted) that can be found within the Pledgecamp Frontend.

Preferred libraries include:

• Charts Chart.js - Simple yet flexible JavaScript charting for designers & developers. Use through the vue-chartjs package
• Internationalisation vue-i18n
• Logging vuejs-logger
• Testing cypress
• Validation validator - String validation library

# Backend Guidelines

For backend work, projects should be based on the Express framework in the case of web systems or ocliff framework in the case of CLIs.

• For environment configuration, aside from Database values, all options should source from a central config component. I.E. No process.env.VAR in the code
• For development use sqlite; for testing use use sqlite in-memory; for production use postgres
• All database interaction should take place from within a table specific utility file located in server/models. See this snippet for an example
• Data that relates to a DB model should be assigned to the same name as used within the schema itself, with two way serialisation occurring at the controller level where possible.

Preferred Libraries include:

• Authentication Passport
• CORS cors - We build frontend services as SPAs so, supporting different domains per service is necessary
• Database knex - Database abstraction layer for relational databases
• Ethereum web3 - Ethereum SDK but, ethereumjs-tx should be used for signing transactions
• Logging Winston FileRotate
• Testing mocha - Testing framework. To be used alongside chai as assertion library, and Sinon as mocking / inspection library