Skip to content

Latest commit

 

History

History
142 lines (90 loc) · 5.45 KB

coding-conventions.md

File metadata and controls

142 lines (90 loc) · 5.45 KB
Raw

Coding Conventions, Linters and Definitions

Some conventions on coding style and tools for the Javascript and Python in this repository.

Definitions

What is a ...

General Coding Conventions

CC1: Can I use TODO:, FIXME:?

We should avoid merging PRs with TODO: and FIXME: into master. One of our bots detects those and flag them as code-smells. If we still want to keep this idea/fix noted in the code, those can be rewritten as NOTE: and should be extended with a link to a github issue with more details. For a context, see discussion here.

CC2: No commented code

Avoid commented code, but if you really want to keep it then add an explanatory NOTE:

import os
# import bar
# x = "not very useful"

# NOTE: I need to keep this becase ...
# import foo
# x = "ok"

CC3: Naming fixtures that return Callables

  • If the callable creates an instance, you can use _factory as suffix instead (e.g. the tmp_path_factory fixture)
  • Use verb as prefix, as seen in the example below
@pytest.fixture
def something() -> Something:
  return Something("nice")

@pytest.fixture
def create_something() -> Callable[..., Something]:

  def _create(*args, **kwargs) -> Something:

    # ...
  return _create

def test_it(something: Something, create_something: Callable[..., Something]):

  new_something = create_something(color="blue")
  assert new_something != something

CC4: ...

Python

In short we use the following naming convention ( roughly PEP8 ):

example
Function function, my_fun­ction
Variable x, var, my_variable
Class Model, MyClass
Method class_­method, method
Constant CONSTANT, MY_CONSTANT, MY_LONG_CONSTANT
Module module.py, my_module.py
Package package, my_package
  • We encourage marking protected/private entities. We do it adding the prefix _/__: e.g. _PROTECTED_CONSTANT, A.__private_func
  • We encourage meaningful type annotations
  • We encourage pep257 for simple code documentation
    • Priorize having good variable names and type annotations than a verbose and redundant documentation
    • Examples of useful documentation:
      • Raised Exceptions in a function
      • Rationale of a design
      • Extra information on variable/argument that cannot be deduced from its name or type annotation
    • Use vscode tool njpwerner.autodocstring
    • See example of pep257 doc.

For the rest ... (tools)

  • black will enforce the style: Just use it.
  • pylint will check the some extra conventions: see .pylintrc.
    • make pylint recipe available on packages or services
  • mypy is a type-checker that will check syntax : see mypy.ini
    • See intro in mypy-doc
    • make mypy recipe available on packages or services

Postgres

  • Foreign Keys follow this name pattern: fk_$(this_table)_$(this_column), for example fk_projects_to_product_product_name

Shell Scripts

Javascript

In general the qooxdoo naming convention/style is followed. The Access paragraph is the most notable. It is recommended to read the entire document.

Have a look at ESLint's configuration files .eslintrc.json and .eslintignore.

My first osparc-simcore PR: common pitfalls

  • Make sure to run make mypy and make pylint, as the associated github-actions are required to pass. If you include new dependencies in requirements/*.in, make sure to run make touch && make reqs "upgrade=NAME_OF_YOUR_NEW_DEPENDENCY". It is best to do this inside a reproducible environment, for this purpose a shell inside a docker container can be used: Go to osparc-simcore/requirements/tools and run make shell. Inside the new shell the osparc-simcore repo is placed in ~. Run make reqs from inside this shell.