sebastian-software / readable-code

[DEPRECATED] Web Coding Standard of Sebastian Software GmbH

Readable Code

Tooling and Configuration for maintainable and readable code for Web Projects.

Goals

• Don't try to prematurely optimize your code; keep it readable and understandable.
• All code in any code-base should look like a single person typed it, even when many people are contributing to it.

"If you want your code to be easy to write, make it easy to read." -- Robert C. Martin

Features

• Automatic detection of Git tracked files for simple to use approach in all projects.

JavaScript

• Includes a sophisticated ESLint configuration. Optimized for readability.
• Contains linting support for ES2017, React, JSX, Flow, Lodash, Accessiblity, etc.
• Includes configuration for prettier in conjunction with ESLints fix mode for automatic sane code configuration.
• Offers gulp tasks lint:js, fix:js and pretty:js for linting, fixing and auto formatting of JavaScript code.

CSS

• Includes configuration for StyleLint
• Offers gulp tasks lint:css and fix:css for linting and auto formatting of CSS code.

Usage

You can copy the relevant files into your own project like .editorconfig.

For ESLint/StyleLint there is a more sophisticated approach: The configuration can be included like shown below:

ESLint Configuration

extends:
  "./node_modules/readable-code/.eslintrc.yml"

Stylelint Configuration

extends:
  "./node_modules/readable-code/.stylelintrc.yml"

Gulp Tasks

We also bundle the whole tooling aspect in here.

You can just import "readable-core" into you gulpfile.js or gulpfile.babel.js for having easy access to some common tasks like lint:js, lint:css, fix:js, fix:css.

Formatting Rules

Common

• Unix line breaks.
• No trailing spaces.
• Indent with 2 spaces no tabs.

JavaScript

• Double quotes for strings and JSX attributes.
• Follow clean code ideas for JavaScript
• Tend to more spaces and whitespace in your code.
• No dashes in file names (should match ^[a-zA-Z][a-zA-Z0-9.]+$).
• All files have a .js extension, no .jsx.
• No CommonJS - use only ES2015 modules.
• Prefer efficient ES2015 language like template strings, spreading, arrow functions, ...
• Keep an eye on code complexity, nesting levels, file length, ...
• Prefer named parameters (destructing) over long parameter lists.
• No usage of labels, with and eval.
• No magic numbers. Use variables to describe intention.

CSS

• Use double quotes for URLs.
• Use one discrete selector per line in multi-selector rulesets.
• Include a single space before the opening brace of a ruleset.
• Include one declaration per line in a declaration block.
• Use one level of indentation for each declaration.
• Include a single space after the colon of a declaration.
• Use lowercase and shorthand hex values, e.g., #aaa.
• Quote attribute values in selectors, e.g., input[type="checkbox"].
• Where allowed, avoid specifying units for zero-values, e.g., margin: 0.
• Include a space after each comma in comma-separated property or function values.
• Include a semi-colon at the end of the last declaration in a declaration block.
• Separate each ruleset by a blank line.

Technology Stack

Gulp (Project | Homepage)

Predefined tasks to import into your custom gulpfile.js.

Stylelint (Project | Homepage)

PostCSS-based linter for CSS. Supports alternative dialects like SugarSS, SCSS and Sass.

Plugins:

• order: Grouping and sorting of rules and properties.

ESLint (Project | Homepage)

Effectively a successor of both JSHint and JSCS. Is configured to use the Babel Parser for full ES2017+ support.

Plugins:

• css-modules: Checks whether CSS classes which are accessed via CSS modules are defined.
• filenames: Validation for file names matching some common sense requirements.
• flowtype: Support for checking FlowType syntax to match rules.
• flowtype-errors: Helps writing correct FlowType declarations.
• import: Checks whether imports map to valid entry points.
• jsx-a11y: Accessibility checks for JSX tags e.g. requiring alt tags on images.
• lodash: Lodash specific checks and hints to prefer common features over custom/builtin.
• no-use-extend-native: Prevent extending native objects/classes like Array or String.
• node: Prevents usage of deprecated features and other checks when developing NodeJS based apps.
• promise: Checks for correctly working with Promises.
• react: React specific checks for requiring specific structures of classes + preferring functional patterns.
• security: Checks for security issues in e.g. RegExps.
• you-dont-need-lodash-underscore: Showcases where ES5 would be a better solution than Lodash.

Prettier (Project)

Auto formatting engine for JavaScript (+ ES2017, JSX, and Flow) which intelligently supports limiting line length and other more advanced features.

Lint Staged (Project)

Auto linting for all .css and .js staged files when these are about to being committed to the repository.

Copyright

Copyright 2015-2017
Sebastian Software GmbH