Development Standards

Intro

To make it a little not-so-harsh for those that actually do understand what are development standards and rules: Your feedback is important to us, and we appreciate the testing and information that you assist us with.

Why do we need coding standards?

The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it.

It makes easier to maintain and read all the scripts related code and gives us more control over the code.

In some cases it will be a safe guard against errors.

Why is it important for developers/contributors?

Make your life and that of maintainers easier! Check everything you do!

Coding Standards

Most of these rules are not specific to the project but to the language itself. However, how to structure a functional code is up to you.

Style errors can be corrected or detected by linters or correctors such as pylint/prospector and black (see below).

You could also read advices from websites like openclassrooms.

Tabs

Python code never contain tabs, instead use spaces. Most sane development-tools have options to replace tabs with 4 spaces.

Whitespaces

No trailing spaces at the end of lines
Do not fill parenthesis with whitespaces
1 space after, but not before a coma, a semicolon, two points

Wrong:

if( attack )
if ( attack )

Correct:

if (attack)

Comments: where

Always comment code where it is not typical code repeated in many/all scripts and/or not self-explanatory what the code does.

Localization of comments:

Above the line
At code line (2 spaces after)
In docstring for important notes

Wrong useless comment:

# if something equals MY_CONSTANT
if (something == MY_CONSTANT)

Error handling

Do not reinvent the wheel.

Use a logger with the available logging levels:

from cutevariant.commons import logger

LOGGER = logger()

LOGGER.debug("My debug string %s", value)  # %s as a placeholder for lazy loading
LOGGER.info(...)
LOGGER.warning(...)
LOGGER.error(...)
LOGGER.exception(...)

Note: Use lazy loading with placeholders in your debugging texts. Values passed as arguments will not be casted into strings if the chosen logging level does not require it.

Don't hide stacktraces! It is better not to handle exceptions than to handle them in a way that will prevent debugging.

What do you prefer ?

ERROR: [mainwindow.py:209:refresh_plugins()] <widgets.FiltersEditorWidget object at 0x7f3cdcf0e348>:205 string indices must be integers

Or:

Traceback (most recent call last):
    File "/media/DATA/Projets/cutevariant/cutevariant/cutevariant/gui/plugins/auragen_filter/widgets.py", line 75, in on_changed
        self.mainwindow.refresh_plugins(sender=self)
    File "/media/DATA/Projets/cutevariant/cutevariant/cutevariant/gui/mainwindow.py", line 205, in refresh_plugins
        plugin_obj.on_refresh()
    File "/media/DATA/Projets/cutevariant/cutevariant/cutevariant/gui/plugins/filters_editor/widgets.py", line 1477, in on_refresh
        self.model.filters = self.mainwindow.state.filters
    File "/media/DATA/Projets/cutevariant/cutevariant/cutevariant/gui/plugins/filters_editor/widgets.py", line 537, in filters
        self.load(filters)
    File "/media/DATA/Projets/cutevariant/cutevariant/cutevariant/gui/plugins/filters_editor/widgets.py", line 734, in load
        self.root_item.append(self.to_item(data))
    File "/media/DATA/Projets/cutevariant/cutevariant/cutevariant/gui/plugins/filters_editor/widgets.py", line 742, in to_item
        [item.append(self.to_item(k)) for k in data[operator]]
    File "/media/DATA/Projets/cutevariant/cutevariant/cutevariant/gui/plugins/filters_editor/widgets.py", line 742, in <listcomp>
        [item.append(self.to_item(k)) for k in data[operator]]
    File "/media/DATA/Projets/cutevariant/cutevariant/cutevariant/gui/plugins/filters_editor/widgets.py", line 745, in to_item
        item = FilterItem((data["field"], data["operator"], data["value"]))
TypeError: string indices must be integers

Look where the 205 of the first text came from... Is it informative?

Thereby, wrong:

try:
    plugin_obj.on_refresh()
except Exception as e:
    print(e)
    LOGGER.error(
        "{}:{} {}".format(
            plugin_obj, format(sys.exc_info()[-1].tb_lineno), e
        )
    )
    raise

Good:

try:
    plugin_obj.on_refresh()
except (ValueError, KeyError) as e:  # Specify the types when possible
    LOGGER.exception(e)

Imports

The order of imports is important to avoid pontential conflicts between libraries.

We discern 2 types of imports:

"Standard" imports first: namely the libs built-ins, then the libs installed via pip
"Custom" imports: imports from the project itself.

For example:

# Standard imports
import json
import vcf
# Custom imports
from .abstractwriter import AbstractWriter

In addition, we avoid relative paths in imports. Prefer the use of absolute paths (starting from the root of the project). This avoids future headaches, if only for local testing of modules: The explicit is always preferable to the implicit. Cf.: https://chrisyeh96.github.io/2017/08/08/definitive-guide-python-imports.html#absolute-vs-relative-import

Magic numbers vs. constants

Try to put your constants in cutevariant.commons if they can be used by many files of the project. Having the same constants at multiple places is error prone during maintenance.

Translations

When doing changes to displayed strings in the GUI, please remember to update the translations.

Docstrings et documentation in general: When to put it/What does it contain

Autodocumented code is a myth. A code that is not or badly documented is of no use to anyone.

Docstrings must answer the questions "what, when, who, why".

The docstring for a function or method should summarize its behavior and document its arguments, returned value(s), side effects, exceptions raised, and restrictions on when and why it can be called (all if applicable).

A developer should not and does not want to have to grep the whole project to guess where and how a function is called, and thus waste his time scrolling up the call stack to know the ins and outs of a piece of code!

As soon as a function is finished and ready to be committed, check the docstring, send your code only once it's done.

In practice, to guide your implementation, you should write the docstring before the code.

Warnings:

Docstrings not acceptable (taken from real code):

"""This function is cute because""" => get straight to the point: "Return x/Do y".

"""Similar to xxxx""" => use standardized reference (see below) """See Also:: :meth:xxx"""

You are in cutevariant/core/writer directory and read: """Expose of high-level reader classes"""
WTF (real) docstrings:

"""As it says""" """Self explained""" """it is clear""" """For tests only"""
Do not make blind Copy/Paste that may insert wrong information or that have nothing to do with the functions you are writing docstrings for.
The docstring is a phrase ending with a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".

Rédaction des docstrings

Python: Docstring Conventions https://www.python.org/dev/peps/pep-0257 https://www.python.org/dev/peps/pep-0287

Writing is based on standards, in Cutevariant you can find 2 standards: ReStructuredText (original and historically recommended for Python), Google Napoleon (new one used for x reasons... especially the annotations (typing hints)).

You will find their respective documentations at the end of this chapter.

If you see the first one, keep using it or rewrite everything in the second standard; DO NOT MIX the two!

Note:

One-line docstrings are accepted for "really obvious cases".
But make no mistake, the return type is not always so obvious that it doesn't require explanation.


Example of good candidate for one-line docstring:

    get_value()

reStructuredText (PEP 287):

"""Summary line.

Extended description of function.

:meth:`other_function`

:example:

coucou

.. note:: blabla
.. warning::

:param int arg1: Description of arg1.
:param str arg2: Description of arg2.
:raise: ValueError if arg1 is equal to arg2
:return: Description of return value
:rtype: bool

:example:

>>> a=1
>>> b=2
>>> func(a,b)
True
"""

Google Napoléon (PEP 484):

Type annotations depend on the typing module used to annotate function signatures:

https://docs.python.org/3/library/typing.html#typing.List
https://mypy.readthedocs.io/en/latest/builtin_types.html#built-in-types

Type                Description
----                -----------

int                 integer of arbitrary size
float               floating point number
bool                boolean value
str                 unicode string
bytes               8-bit string
object              an arbitrary object (object is the common base class)
List[str]           list of str objects
Dict[str, int]      dictionary from str keys to int values
Iterable[int]       iterable object containing ints
Sequence[bool]      sequence of booleans
Any                 dynamically typed value with an arbitrary type

Typing hints may seem to overload function signatures, however the description of argument and return types is absolutely necessary. They must be written, checked, and updated in case of modification of any function!

Full example:

from typing import Union, Text

def fetch_bigtable_rows(big_table, keys, other_silly_variable: Union[None, Text, int])): # or var: Optional[Text] = None
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys (List[str]): A sequence of strings representing the key of each table row
            to fetch.
            =>
        other_silly_variable (bool): Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Kwargs:
        other_silly_variable (Optional[bool]): Current state to be in.
            => boolean or None

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
        'Zim': ('Irk', 'Invader'),
        'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """

Links:

Python guide Google Napoléon/Sphinx
https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings


Official ReSt doc from sphinx
http://www.sphinx-doc.org/en/1.6/domains.html#cross-referencing-python-objects

ReStructuredText/Google-style/Numpy-stylem/Doctests
https://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html
http://queirozf.com/entries/python-docstrings-reference-examples
https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format

Naming of variables, classes, functions and methods

Syntaxes allowed/recommended in Python:

snake_case for functions and variables
CamelCase for classes

Additional rules:

A function name should be something sweet, short and meaningful about what the function does.
Remember to use the plural form when designating structures with multiple items.
Be explicit but not too much. Do not put sentences in your variables!
Do not use variable with less than 3 letters; EVEN in comprehension loops.
Do not reuse variables for different purposes than the original one.
Be consistent: a variable named map_x should not be found elsewhere with the name x_map.