Coding

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 Zen, most of the Python coding guidelines are automatically checked by the following linters:

• pycodestyle

• Pylint

• isort

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 Zen, 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 Zen , 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 Zen, 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.