Do’s and Don’ts

Do’s and Don’ts#

This page is dedicated to a non-exhaustive list of best practices we would like to mention.

Don’t hardcode paths#

Avoid hardcoding absolute paths in your code. This ensures your project is portable and works on any system.

If you are pasting a path starting with “C:\…” into your code, then you are doing something wrong. Other people won’t have access to these files and your code won’t be reproducible.

How to avoid it in Python:

  • Use relative paths:

    import os

BASE_DIR = os.path.dirname(__file__)
data_path = os.path.join(BASE_DIR, "data", "input.csv")

  • Use `pathlib` for cleaner path handling:

    from pathlib import Path

BASE_DIR = Path(__file__).parent
data_file = BASE_DIR / "data" / "input.csv"

An example is also provided in the example project

Don’t publish your credentials to a git repo#

Never commit sensitive information such as passwords, API keys, or private SSH keys to a Git repository. This can expose your accounts and services to unauthorized access. Thanks to Git versioning, these credentials will remain available even after you remove them!

How to avoid it in Python:

  • Use a .env file to store credentials:

    # .env
API_KEY=your_api_key_here
DB_PASSWORD=supersecret

  • Add .env to your .gitignore so it is never committed.

  • Load the values in your code using the library python-dotenv:

    from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("API_KEY")
db_password = os.getenv("DB_PASSWORD")

Don’t track large data files on git#

You should avoid storing large amounts of data directly in GitLab because Git isn’t designed for big files or datasets. Large files quickly bloat the repository since Git tracks their entire history.

Instead, add the data directory of your project to .gitignore or use the Git LFS (Large File Storage) function which is dedicated to versioning large files.

Use Virtual Environments in Python#

Python projects should use virtual environments to isolate dependencies and avoid conflicts between projects.

See Create a virtual environment

Choose a license#

Licensing your code sets clear rules for how others can use, share, or modify it. Without a license, your work is legally “all rights reserved,” which discourages collaboration and reuse. By choosing a license, you protect yourself, ensure attribution, and decide whether your code can be used commercially or must remain open source. In short, licensing builds trust and helps your work reach more people.

Please refer to the ERIC Documentation to choose your license.

Document your code#

Writing clear documentation makes your code easier to use, maintain, and share.

Key steps:

  • Include a README with project purpose, setup instructions, and usage examples.

  • Add inline comments and docstrings for functions and classes.

  • Use Sphinx or other documentation tools to generate documentation pages like this one. Spinx makes it possible to directly integrate the docstrings from your code. You can add a .gitlab-ci.yml file so the documentation is published to GitLab pages everytime you push.

Separate requirements for developers and setup#

It is good practice to separate dependencies needed to run your project from those needed to develop and maintain it.

  • Create a requirements.txt (or pyproject.toml) that lists only the runtime dependencies.

  • Create a requirements-dev.txt (or equivalent) that lists extra packages for development, such as testing, linting, or documentation tools.

This separation keeps the production environment lean and prevents unnecessary tools from being installed on systems that only need to execute your code.

Example requirements-dev.txt:

-r requirements.txt
pytest
sphinx
black
pre-commit

Test your code#

Adding automated tests ensures that your code works as expected and prevents bugs from creeping in when you make changes.

Best practices:

  • Use the pytest framework for writing tests.

  • Place tests in a dedicated tests/ directory at the root of your project.

  • Aim for both unit tests (testing small functions or classes) and integration tests (testing workflows or data pipelines).

  • Run tests locally before committing, and set up Continuous Integration (CI) in GitLab to automatically run them on each push.

Publish your code as a package#

Packaging your project makes it easier to share, install, and reuse. This is especially important if others will depend on your code.

Key steps:

  • Include a pyproject.toml (preferred) or setup.py file with project metadata such as name, version, and dependencies.

  • Follow the standard Python packaging guidelines from PyPA.

  • Use setuptools or flit for building packages.

  • Optionally, publish your package to PyPI or a private GitLab package registry so others can install it with pip install yourpackage.

Contents