Linting
This page explains the linting rules in place for the various tools and languages in use at SKAO. For detailed instructions, see the how-to guides.
Python & Jupyter Notebooks Coding Style/Conventions
The SKAO enforces the following coding style rules and conventions for Python and Jupyter Notebooks:
The code will follow the standard PEP8 Style Guide for Python Code. In particular, this includes using only 4 spaces for indentation, and never tabs.
The
import numpy as np
,import matplotlib as mpl
, andimport matplotlib.pyplot as plt
naming conventions should be used wherever relevant.from packagename import *
should never be used, except as a tool to flatten the namespace of a module. An example of the allowed usage is given in Acceptable use of from module import *.Classes should either use direct variable access, or Python’s property mechanism for setting object instance variables.
get_value
/set_value
style methods should be used only when getting and setting the values requires a computationally-expensive operation. Properties vs. get_/set_ below illustrates this guideline.Classes should use the builtin
super()
function when making calls to methods in their super-class(es) unless there are specific reasons not to.super()
should be used consistently in all subclasses since it does not work otherwise. super() vs. Direct Calling illustrates why this is important.Multiple inheritance should be avoided in general without good reason.
__init__.py
files for modules should not contain any significant implementation code.__init__.py
can contain docstrings and code for organizing the module layout, however (e.g.from submodule import *
in accord with the guideline above). If a module is small enough that it fits in one file, it should simply be a single file, rather than a directory with an__init__.py
file.
The python source code should be automatically validated using the pipeline machinery, which uses the isort
, black
, flake8
and pylint
tools to enforce the above guidelines.
C++ Coding Style/Conventions
The SKAO recommends that new software follow The C++ Core Guidelines. However, no automated linting exists.
Ansible Coding Style/Conventions
Ansible playbooks should be automatically validated using the pipeline machinery, which uses the yamllint
, ansiblelint
and flake8
tools to enforce default guidelines.
Helm Coding Style/Conventions
Helm charts should be automatically validated using the pipeline machinery, which uses the yamllint
tool to enforce default guidelines.
OCI Coding Style/Conventions
OCI images should be automatically validated using the pipeline machinery, which uses the hadolint
tool to enforce default guidelines.
Terraform Coding Style/Conventions
Terraform files should be automatically validated using the pipeline machinery, which uses the tflint
tool to enforce default guidelines.
VHDL Coding Style/Conventions
The VHDL coding guidelines developed and published by ALSE are excellent, and form the basis of this coding guideline. They are available from their website:
http://www.alse-fr.com/VHDL-Coding-Guide.html
and as a pdf:
http://www.alse-fr.com/sites/alse-fr.com/IMG/pdf/vhdl_coding_v4_eng.pdf.
The following numbered additions/modifications/clarifications are used:
The VHDL-2008 standard will be used, so far as its features are supported by synthesis and simulation tools. Synthesis tools’ support for VHDL-2008 features has improved to a level where its usage can result in simpler, less verbose, and more descriptive code.
P_11) VHDL keywords shall be in lower case. Use an editor with syntax highlighting.
N_8) Active low signals should be avoided. In preference signals should be named to make them active high (positive logic). If no such obvious name can be found then active low signal names should have the suffix _n. For example the following are equivalent:
tx_disable == tx_enable_n.
Note that in VHDL 2008, operators can be applied in port maps. So conversion can be applied without having to create an intermediate signal (and hence specify a name for it). For example:
E_EXT_MOD : entity extern_lib.module
port map ( ...
i_tx_enable_n <= not tx_enable,
...);
N_9) When ports of mode ‘out’ need to be accessed internally, the derived internal signals shall be named using <out port name>_i (for example o_outbus_i being the internally accessible signal from which the output port o_outbus is directly derived. However, in VHDL-2008 the output port can be accessed directly making this irrelevant.
N_10) Use instance names derived from the entity names. Prefix E_ should be used to identify the direct instantiation of the entity, and C_ for instantiation from a component declaration. The label shall be in all upper case. For example:
E_FIR16X8 : entity work.fir16x8 port map ( etc...
C_FIR16X8 : fir16x8 port map ( etc…
If there are multiple instances then instance names should have a descriptor appended that adds information. Avoid simply appending a number (consider using a generate loop instead). For example:
E_EMIF_BOTTOM_RIGHT : entity work.external_memory_interface port map ( ...
E_EMIF_TOP_LEFT : entity work.external_memory_interface port map ( ...
E_EMIF_TOP_RIGHT : entity work.external_memory_interface port map ( ...
N_14) Names for clock and reset signals shall conform to the following convention:
Clocks:
<name>_clk
Reset:
<name>_clk_<reset_name>_rst
(active high reset, synchronised to<name>_clk
)Reset:
<name>_clk_<reset_name>_rst_n
(active low reset, synchronised to<name>_clk
)
<name>
should be shared with the signals in the clock’s domain.
An entity with a single clock, should have the input clock i_clk
, and with a single active high synchronous reset i_clk_rst
.
N_15) Constants shall use the c_ prefix, and the name be capitalised, for example:
constant c_BYTE_WIDTH : natural := 8;
N_11) Generics shall use the g_ prefix, and the name be capitalised, for example:
generic (g_BLOCK_LENGTH : natural := 256);
N_12) Variables shall use the v_ prefix, for example:
variable v_sum : unsigned(7 downto 0);
N_13) Process labels shall use the P_ prefix, and be capitalised for example:
P_DO_READ : process(i_clk)
Begin
if rising_edge(i_clk) then
...
end if;
end process P_DO_READ;
N_12) Generate labels should use the G_ prefix, and be capitalised, for example:
G_USE_BUFFER : if not g_SIM generate
-- instantiate buffer module
else generate
-- default signal assignments
end generate G_USE_BUFFER;
G_EACH_DATA : for idx in 0 to g_DATA_WIDTH-1 generate
-- assignments/instantiations for each bit in the data.
end generate G_EACH_DATA;
C_6a) Allow numeric_std version of unsigned and signed types in ports. This increases the information in port description, giving meaning to the bit vector that is not available when declared as a std_logic_vector.
Note
Further discussion on firmware development process, continuous integration, automated testing and recommendations for best practices can be found in the following google doc. This document will be gradually implemented and the resulting decision will be included in this developer portal.
https://docs.google.com/document/d/1Kfc_4vLUy-0pSbi9HVeEkAmhuvEIEnt4voFnXxsc0zM/edit?usp=sharing