Commit 30e574c7 authored by Dominique Barton's avatar Dominique Barton 🦄
Browse files

DOC: Add coding guidelines

parent 70a3c7fb
Pipeline #12838 failed with stage
in 37 seconds
Coding
======
The Zen of confirm
------------------
The idea of **The Zen of confirm** is highly inspired by `The Zen of Python <https://www.python.org/dev/peps/pep-0020/>`_ and must be our dogma for maintainable solutions:
- Beautiful is better than ugly.
- Explicit is better than implicit.
- Simple is better than complex.
- Complex is better than complicated.
- Flat is better than nested.
- Sparse is better than dense.
- Readability counts.
- Consistency matters.
- Special cases aren't special enough to break the rules.
- Although practicality beats purity.
- Errors should never pass silently.
- Unless explicitly silenced.
- In the face of ambiguity, refuse the temptation to guess.
- There should be one - and preferably only one - obvious way to do it.
- If the implementation is hard to explain, it's a bad idea.
- If the implementation is easy to explain, it may be a good idea.
- Namespaces are one honking great idea - let's do more of those!
Python Coding Gudielines
------------------------
Apart from `The Zen of confirm`_, most of the Python coding guidelines are automatically checked by the following :ref:`linters <linter introduction>`:
- :ref:`pycodestyle`
- :ref:`pylint`
- :ref:`isort`
HTML Coding Guidelines
----------------------
Apart from `The Zen of confirm`_, the following rules apply especially to HTML:
- Attributes use the ``kebab-case`` format.
- Boolean attributes will not use prefixes like ``is…``, ``has…``, ``can…``.
JavaScript Coding Guidelines
----------------------------
Apart from `The Zen of confirm`_, most of the JavaScript coding guidelines are automatically checked by the :ref:`eslint`.
However, the following rules apply especially to JavaScript:
- Vanilla JavaScript is better than frameworks.
- ECMAScript 6 is better than their predecessors.
- Backward compatibility is not required and can be ignored.
- The ``id`` attribute must be used to query unique / distinct elements in JavaScript.
- The ``#id`` selector must never be used for CSS styling.
.. hint::
Also have a look at the `Web Components Guidelines`_, as JavaScript is also a part of `Web Components`_.
CSS Coding Guidelines
---------------------
Apart from `The Zen of confirm`_, most of the CSS coding guidelines are automatically checked by the :ref:`stylelint`.
However, the following rules apply especially to CSS:
- Vanilla CSS is better than `Sass <https://sass-lang.com/>`_ or `Less.js <https://lesscss.org/>`_.
- CSS classes must use the ``kebab-case`` format.
.. hint::
Also have a look at the `Web Components Guidelines`_, as CSS is a part of `Web Components`_.
Web Components Guidelines
-------------------------
For `Web Components <https://developer.mozilla.org/en-US/docs/Web/Web_Components>`_ the following rules apply:
- Web components must only be customisable by attributes.
- Passing CSS classes to web components is prohibited.
- CSS selectors directly on the ``:host()`` are preferred over any layer of indirection or abstraction.
- `BEM <http://getbem.com/>`_, `OOCSS <https://www.keycdn.com/blog/oocss>`_, `SMACSS <http://smacss.com/>`_ or alike must not be used at all.
.. hint::
Since web components use all web technologies, `HTML <HTML Coding Guidelines>`_, `JavaScript <JavaScript Coding Guidelines>`_ & `CSS <CSS Coding Guidelines>`_ coding guidelines are also applied to `Web Components`_.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment