Tunga General Development Guidelines

Glossary:

API - Application Programming Interface

DRY - Don’t Repeat Yourself

IDE - Integrated Development Environment

LTS - Long Term Support

oData - Open Data Protocol

REST - Representational State Transfer

SOAP - Simple Object Access Protocol

VCS - Version Control System

Guidelines:

Code quality:

• Don’t reinvent the wheel, leverage existing libraries and frameworks.
• Write DRY and modular code by leveraging available language constructs like inheritance, interfaces, mixins and closures where possible.
• Follow language, framework and platform conventions, styles and architectural guides to keep code readable and easy to maintain e.g iOS https://developer.apple.com/libr…, Android https://developer.android.com/guide/, Python https://www.python.org/dev/peps/pep-0008/, Java https://google.github.io/styleguide/javaguide.html
• Leverage standardized architectures and protocols when building web services e.g REST, SOAP, oDATA.
• Use linters https://github.com/collections/clean-code-linters and editorconfig files http://editorconfig.org/ to define coding styles.

Dependency management:

• Use industry standard dependency management tools (e.g bundler for Ruby, pip for Python, npm or yarn for NodeJS, bower for JavaScript, maven for Java).
• Leverage a module bundler for frontend JavaScript projects (e.g webpack https://webpack.js.org/).
• Use stable and LTS versions (where possible) of all development tools (including languages, libraries, frameworks, VCS and dependency management tools) to ensure quick bug fixes and security updates
• Commit lock files generated by dependency management tools to VCS for deterministic dependency resolution.

Version Control:

• Use a modern VCS to manage code e.g Git (preferrably because of widespread adoption), mercurial or subversion.
• Backup source code with a cloud based hosting service e.g GitHub (free for public https://github.com/), Bitbucket (free for private but has limit on size of team https://bitbucket.org/product), Gitlab (free for unlimited team members and number of repos https://about.gitlab.com/).
• Keep IDE setup files out of VCS (e.g .idea and .vscode folders).
• The master branch should only include code ready for production, as such, don’t work directly from the master branch. Always create feature branches for contributing/adding new features or create a generic branch e.g “develop” for changes which are not yet ready for production.

Versioning:

• Follow semver (https://semver.org/) for versioning.
• Create version tags for important releases in the VCS.
• Use API versioning to prevent breaking dependent client applications when updating mature (already in production and consumed by other live/production clients) APIs.

Secrets, passwords and private keys:

• Keep secrets, passwords and private keys out of the VCS.
• Store secrets and passwords as environment variables or using .env files that are not committed to the VCS.

Documentation:

• Create readme files to make it easy for other contributors to set up and check out the project.
• Define a data dictionary for applications with a storage layer.
• Leverage the OpenAPI https://github.com/OAI/OpenAPI-Specification specification and related libraries to generate API documentation that is easily maintainable.

Logging:

• Leverage modern tools for error and exception logging and tracking e.g Sentry https://sentry.io/welcome/ and Crashlytics https://try.crashlytics.com/

Deployment, build and tests:

• Leverage automated deployment (e.g Ansible https://www.ansible.com/, Capistrano http://capistranorb.com/, Chef https://www.chef.io/chef/)
• Leverage automated build tools (e.g Gradle https://docs.gradle.org/current/userguide/userguide.html)
• Leverage unit testing tools and libraries to create automated testing facilities that can be run before integration and deployment.
• Leverage continuous integration tools like travis CI https://travis-ci.org/ and circleCI https://circleci.com/
• Add asset minification and optimization (e.g HTML, JavaScript and CSS minification for web development and image optimization for general development) to your build pipelines.

Pull requests:

• Keep pull requests focused in scope with one pull request per issue and avoid including unrelated commits.
• When fixing issues or adding features, squash all commits in the pull request.