Coding ====== Data structure guidelines ------------------------- Think about the format of your data structures, especially for extendible ones. For example: .. code-block:: python # 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 :ref:`Zen`, most of the Python coding guidelines are automatically checked by the following :ref:`linters `: - :ref:`pycodestyle` - :ref:`pylint` - :ref:`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: .. code-block:: python 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: .. code-block:: python def spam(): ''' Provides SPAM. .. seealso:: :py:meth:`spam.eggs.Egg.boil` The method used to boil eggs. ''' HTML coding guidelines ---------------------- Apart from :ref:`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 :ref:`Zen` , 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. .. hint:: Also have a look at the `Web Components Guidelines`_, as JavaScript is also a part of `Web Components`_. CSS coding guidelines --------------------- Apart from :ref:`Zen`, 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 `_ 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`_.