Overview

• Overview
  • Installation
  • Documentation
  • Contributing
    • Creating the virtual environment
    • Linting
    • Documentation
    • Naming Convention
    • Code Structure

Installation

Install Plot Serializer with pip:

pip install plot-serializer

Documentation

View Plot Serializer's documentation on Read the Docs

Contributing

Clone this repository with

git clone git@git.rwth-aachen.de:fst-tuda/projects/rdm/plot-serializer.git

Creating the virtual environment

On Windows, run

py -m venv env

The second argument is the location to create the virtual environment. Generally, you can just create this in your project and call it env.

venv will create a virtual Python installation in the env folder.

Before you can start installing or using packages in your virtual environment you’ll need to activate it. Activating a virtual environment will put the virtual environment-specific python and pip executables into your shell’s PATH.

.\env\Scripts\activate

You can confirm you’re in the virtual environment by checking the location of your Python interpreter:

where python

Tell pip to install all of the packages in the requirements.txt file using the -r flag:

py -m pip install -r requirements.txt

Update the requirements.txt file when you install new packages.

For more detailed instructions, check https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/.

Linting

This project uses the flake8 linter and the black autoformatter.

Documentation

Documentation is an essential part of writing code.

⚠️ All public functions, methods, classes and modules must be properly documented with docstrings.

This project uses google-style docstrings. An example for a good docstring:

def find_largest_distance(point, polygon):
    """Finds the largest distance between a point and the edges of a polygon.

    Args:
        point (shapely.geometry.Point): shapely point object
        polygon (shapely.geometry.Polygon): shapely polygon object

    Returns:
        float: the largest distance between a point and the edges of a polygon
    """
    distance_list = np.array([])
    for poly_point in list(zip(*polygon.exterior.coords.xy)):
        distance = point.distance(Point(poly_point))
        distance_list = np.append(distance_list, distance)
    max_distance = max(distance_list)
    return max_distance

because:

• short and easy to understand description
• starts with a verb in third person
• type of the args are given
• args and returns are described sufficiently

Where necessary, add additional information using comments.

Naming Convention

Follow Guido's recommendations (taken from Google Python Styleguide):

Type	Public	Internal
Packages	lower_with_under
Modules	lower_with_under	_lower_with_under
Classes	CapWords	_CapWords
Exceptions	CapWords
Functions	lower_with_under()	_lower_with_under()
Global/Class Constants	CAPS_WITH_UNDER	_CAPS_WITH_UNDER
Global/Class Variables	lower_with_under	_lower_with_under
Instance Variables	lower_with_under	_lower_with_under (protected)
Method Names	lower_with_under()	_lower_with_under() (protected)
Function/Method Parameters	lower_with_under
Local Variables	lower_with_under

For better readability, use meaningful, expressive names instead of hard-to-understand short names. Don’t drop letters from your source code. Although dropped letters in names like memcpy (memory copy) and strcmp (string compare) were popular in the C programming language before the 1990s, they’re an unreadable style of naming that you shouldn’t use today. If a name isn’t easily pronounceable, it isn’t easily understood.

Additionally, feel free to use short phrases that can make your code read like plain English. For example, number_of_trials is more readable than simply number_trials.

More on naming.

Use a spell checker.

Code Structure

The maximum line length is 120 characters.

Whitespaces should be automatically deleted; the autoformatter should take care of this.

Improve readability by limiting the number of nested statements.

Preferrably write short functions, and pure functions that can be tested.