@puzzleitc/frontend-guides

Puzzle Frontend Coding Guidelines

This repository provides guidelines, recommendations and code conventions for JavaScript, TypeScript, CSS and HTML to be used in software projects at Puzzle ITC. According to the Puzzle QM Guide, code conventions must be used and automatically verified in software projects.

Please contact the frontend workgroup for questions or create pull requests for improvements.

General

EditorConfig

EditorConfig helps define and maintain consistent coding styles between different editors and IDEs (supporting editors/IDEs).

Put the following .editorconfig file in your frontend application's root:

# http://editorconfig.org

root = true

[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.{diff,md}]
insert_final_newline = false
trim_trailing_whitespace = false

Yarn

Always use the Yarn package manager instead of NPM. It uses a lock file for deterministic and faster installations.

Don't install Yarn using NPM, see Installation.

To setup Yarn on Jenkins, read these instructions.

Linting & Fixing

Use either eslint (JavaScript) or tslint (TypeScript) to enforce code conventions. Add the package @puzzleitc/frontend-guides to your project and provide the appropriate linter configuration as described below.

You may use eslint --fix '**/*.js' or tslint --fix '**/*.ts' to automatically fix linting issues where possible.

JavaScript

Consider the Airbnb JavaScript Style Guide.

Add the Puzzle linting rules to your project:

yarn add --dev @puzzleitc/frontend-guides

Add .eslintrc.js:

module.exports = require('@puzzleitc/frontend-guides/eslint/config');

Recommendations:

• Lean towards NPM scripts (see Why I Left Gulp and Grunt for npm Scripts), otherwise use Gulp
• If you need a module bundler: use Webpack
• TODO: transpiling

AngularJS

In addition to the Airbnb Guide, consider John Papa's Angular 1 Style Guide for code conventions and application structure. Use eslint-plugin-angular to enforce these rules.

Add the Puzzle linting rules to your project:

yarn add --dev @puzzleitc/frontend-guides

Add .eslintrc.js:

module.exports = require('@puzzleitc/frontend-guides/eslint/config/ng');

TypeScript

Consider the Airbnb JavaScript Style Guide.

Add the Puzzle linting rules to your project:

yarn add --dev @puzzleitc/frontend-guides

Add tslint.json:

{
  "extends": ["@puzzleitc/frontend-guides/tslint/config"]
}

Recommendations:

• Use strict type checking ("strict": true under compilerOptions in tsconfig.json)

Angular

In addition to the Airbnb Guide, consider the official Angular Style Guide for code conventions and application structure. Use codelyzer to enforce these rules.

Add the Puzzle linting rules to your project:

yarn add --dev @puzzleitc/frontend-guides

Add tslint.json:

{
  "extends": ["@puzzleitc/frontend-guides/tslint/config/ngx"]
}

Recommendations:

• Use TypeScript
• Use Webpack or the Angular CLI

Cascading Style Sheets

Consider Github's Primer Code Guidelines.

TODO:

• SASS usage
• postCSS/autoprefixer/cssnano
• SMACSS?

Hypertext Markup Language

Consider Github's Primer Code Guidelines.

Images & Icons

TODO:

• inline SVG
• optimization?

Preferred Packages & Widgets

TODO:

• Selectize
• Testing (AngularJS & Angular): Karma/Jasmine
• ...