Coding

The zen of confirm

The idea of the zen of confirm is highly inspired by The Zen of Python 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!

Data structure guidelines

Think about the format of your data structures, especially for extendible ones. For example:

# This works.
spam = ['i', 'hate', 'spam']

# But this is much better.
eggs = [
    'i',
    'like',
    'eggs',
]

Hint

If you’re expanding both lists and you make a diff, you’ll notice that the changes of spam are much harder to tell than the changes of eggs. Therefor prefer the multi- over the single-line format. Also make sure you always add a trailing comma to the last element as well.

Python coding guidelines

Apart from the zen of confirm, most of the Python coding guidelines are automatically checked by the following linters:

Make extensive use of Python’s docstrings. Also use the Sphinx info fields notation to document things like arguments or return values.

Here’s an example:

def spam(eggs):
    '''
    Add SPAM to ``eggs``.

    :param str eggs: The eggs

    :return: The eggs with SPAM
    :rtype: str
    '''
    return eggs ' with SPAM'

Cross-referencing should also be made with the Sphinx Python domain notation, for example:

def spam():
    '''
    Provides SPAM.

    .. seealso::

        :py:meth:`spam.eggs.Egg.boil`
            The method used to boil eggs.
    '''

HTML coding guidelines

Apart from the zen of confirm, the following rules apply especially to HTML:

ID’s must use the kebab-case format.
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 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.

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 stylelint.

However, the following rules apply especially to CSS:

Vanilla CSS is better than Sass or Less.js.
CSS classes must use the kebab-case format.
CSS .class selectors must be used for styling when multiple elements are affected
CSS #id selectors can (!= must) be used for styling when only one element is affected
BEM, OOCSS, SMACSS or alike must not be used at all.

Hint

Also have a look at the Web Components Guidelines, as CSS is a part of Web Components.

Web Components guidelines

For 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.

Hint

Since web components use all web technologies, HTML, JavaScript & CSS coding guidelines are also applied to Web Components.