Coding Style

Having a clean and structured code is very important for the sustainable development of this project. Cuckoo Sandbox is a good example. So we follow most of their style for maintaining the code base.

We do help out with code refactoring where required, but please try to do as much as possible on your own.

Essentially Quark’s code style is based on PEP 8 - Style Guide for Python Code and PEP 257 – Docstring Conventions.

Formatting

File and folder naming

All characters in the filenames or folder names should be lowercase letters.

Copyright header

All existing source code files start with the following copyright header:

# This file is part of Quark Engine - https://quark-engine.rtfd.io
# See GPLv3 for copying permission.

Indentation

The code must have a 4-spaces-tabs indentation. Since Python enforce the indentation, make sure to configure your editor properly or your code might cause malfunctioning.

Maximum Line Length

Limit all lines to a maximum of 79 characters.

Blank Lines

Separate the class definition and the top level function with one blank line. Methods definitions inside a class are separated by a single blank line:

class MyClass:
    """Doing something."""

    def __init__(self):
        """Initialize"""
        pass

    def do_it(self, what):
        """Do it.
        @param what: do what.
        """
        pass

Use blank lines in functions, sparingly, to isolate logic sections. Import blocks are separated by a single blank line, import blocks are separated from classes by one blank line.

Imports

Imports must be on separate lines. If you’re importing multiple objects from a package, use a single line:

from lib import a, b, c

NOT:

from lib import a
from lib import b
from lib import c

Always specify explicitly the objects to import:

from lib import a, b, c

NOT:

from lib import *

Strings

Strings must be delimited by double quotes (“).

Printing and Logging

We discourage the use of print(): if you need to log an event please use Python’s logging which is already initialized by Quark.

In your module add:

import logging
log = logging.getLogger(__name__)

And use the log handle. More details can be found in the Python documentation, but as follows is an example:

log.info("Log message")

Exceptions

Custom exceptions will be defined in the quark/utils/exceptions.py file.

Naming

Custom exception names must start with “Quark” and end with “Error” if it represents an unexpected malfunction.

Exception handling

When catching an exception and accessing its handle, use as e:

try:
    foo()
except Exception as e:
    bar()

NOT:

try:
    foo()
except Exception, something:
    bar()

It’s a good practice use “e” instead of “e.message”.

Documentation

All code must be documented in docstring format, see PEP 257 – Docstring Conventions. Additional comments may be added in logical blocks to make the code easier to understand.

As for the contribution to quark rtdf. Please use make html to build the html files. And commit with rst files altogether. So that users can read docs when offline.

Automated testing

We believe in automated testing to provide high quality code and avoid easily overlooked mistakes.

When possible, all code must be committed with proper unit tests. Particular attention must be placed when fixing bugs: it’s good practice to write unit tests to reproduce the bug. All unit tests and fixtures are placed in the tests folder in the quark-engine/tests.

We have adopted Pytest as unit testing framework. Also we adopted travis ci for the continuous integration.