Skip to content

Coding Standards Document

Introduction

Overview

Maintaining high-quality, readable, and maintainable code is paramount for the success of any software project. This document outlines the Coding Standards enforced within the cookiecutter-collabora Python template. By adhering to these standards, developers ensure consistency, reduce bugs, and facilitate collaboration across teams.

Dual Enforcement

These standards are both implicit and explicitly enforced through a combination of tools and configuration files. This document serves to make these standards explicit, providing clear guidelines for all contributors.

Code Formatting

1. Why We Use a Formatter

Purpose of Code Formatters

A code formatter automatically enforces a consistent code style across the project. This enhances readability, reduces diffs in version control, and minimizes stylistic disagreements among team members. By standardizing the code layout, developers can focus on functionality rather than formatting nuances.

2. What is Black Formatter

Black Formatter Overview

Black is the primary code formatter used in the cookiecutter-collabora template. It enforces a uniform coding style by formatting Python code according to its uncompromising rules. Black aims to reduce the time spent on formatting decisions, allowing developers to write code without worrying about stylistic inconsistencies.

3. Coding Standards Using Black

Black Coding Standards

  • Line Length: 79 characters to maintain readability across various editors and interfaces.
  • Target Python Version: Python 3.10 to leverage the latest language features.
  • File Types Included: Formats .py, .pyi, and .ipynb files to ensure consistency across Python scripts and Jupyter notebooks.

4. How Black Has Been Configured and Where

Black Configuration
pyproject.toml
[tool.poetry.dependencies]
black = { version = "23.7.0", extras = ["jupyter"] }

[tool.black]
line-length = 79
target-version = ['py310']
include = '''
(
    \.pyi?$
  | \.ipynb$
)
.vscode/settings.json
"[python]": {
"editor.defaultFormatter": "ms-python.black-formatter",
"editor.formatOnSave": false
},
.vscode/extensions.json
"ms-python.black-formatter",

5. How Black Has Been Enforced

Enforcement Notice

Enforcement: - Pre-commit Hooks: Automatically formats code on pre-commit via the black and black-jupyter hooks, ensuring that all committed code adheres to the defined style. - Editor Integration: Configured in VSCode with the ms-python.black-formatter extension, providing real-time formatting as developers write code.

.pre-commit-config.yaml
- repo: https://github.com/psf/black-pre-commit-mirror
  rev: 24.4.2
  hooks:
    - id: black
      name: black-formatter
      language_version: python3.10
    - id: black-jupyter
      name: black-jupyter-formatter
      language_version: python3.10

Ruff Linter

1. Why We Use a Linter

Purpose of Linters

A linter automatically analyzes code to identify potential errors, enforce coding standards, and improve overall code quality. By integrating a linter like Ruff, we ensure that our codebase remains clean, consistent, and free from common issues, which enhances maintainability and reduces the likelihood of bugs.

2. What is Ruff Linter

Ruff Linter Overview

Ruff is a fast and efficient Python linter that checks for syntax errors, enforces coding standards, and applies various code quality checks. It supports a wide range of rules, including those from Pyflakes, pycodestyle, isort, pep8-naming, and pydocstyle, making it a comprehensive tool for maintaining high code quality.

3. Coding Standards Using Ruff

Ruff Coding Standards

  • Selected Rules: A comprehensive set covering Pyflakes, pycodestyle, isort, pep8-naming, and pydocstyle to ensure code correctness and adherence to best practices.
  • Line Length: 79 characters to maintain readability across different editors and interfaces.
  • File Types Included: .py, .pyi, .ipynb, and pyproject.toml to ensure consistency across Python scripts, type hint files, Jupyter notebooks, and configuration files.

4. How Ruff Has Been Configured and Where

Ruff Configuration
pyproject.toml
[tool.poetry.dev-dependencies]
ruff = "0.4.9"

[tool.ruff]
select = [
    # Pyflakes (F) rules
    "F401", "F402", "F403", "F405", "F601", "F602", "F621", "F631",
    "F632", "F701", "F702", "F704", "F706", "F707", "F722",
    "F811", "F821", "F841",
    # pycodestyle (E, W) rules
    "E101", "E111", "E112", "E113", "E114", "E115", "E116",
    "E117", "E201", "E202", "E203", "E211", "E225", "E231",
    "E251", "E261", "E262", "E265", "E266", "E271", "E272",
    "E273", "E274", "E275", "E401", "E402", "E501",
    "E711", "E712", "E713", "E714", "E721", "E722", "E731",
    # isort (I) rules
    "I001", "I002",
    # pep8-naming (N) rules
    "N801", "N802", "N803", "N804", "N805", "N806",
    # pydocstyle (D) rules
    "D100", "D101", "D102", "D103", "D104", "D105",
    "D106", "D107",
]
line-length = 79
include = ["*.py", "*.pyi", "**/pyproject.toml", "*.ipynb"]
.vscode/settings.json
{
    "ruff.args": [
        "--config=pyproject.toml",
        "--preview"
    ],
    "ruff.path": [
        "/bin/ruff"
    ],
    "ruff.interpreter": [
        "/bin/python"
    ],
    "editor.rulers": [
        72,
        79
    ],
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnSave": false
    },
    "charliermarsh.ruff.enable": true
}
.vscode/extensions.json
{
    "recommendations": [
        "charliermarsh.ruff",
        "ms-python.black-formatter",
        // other extensions...
    ]
}

5. How Ruff Has Been Enforced

Enforcement Notice

Enforcement: - Pre-commit Hooks: Automatically enforces coding standards on pre-commit via the ruff hook, ensuring that all committed code adheres to the defined style and quality rules. - Editor Integration: Configured in VSCode with the charliermarsh.ruff extension, providing real-time linting and feedback as developers write code.

.pre-commit-config.yaml
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.4.9
  hooks:
    - id: ruff
      name: ruff-linter
      types_or: [python, pyi, jupyter]
      args: ["--config=pyproject.toml", "--fix", "--preview"]

Static Type Checking

1. Why We Use a Type Checker

Purpose of Type Checkers

A type checker like MyPy statically analyzes Python code to ensure that type annotations are correctly implemented. This helps in catching type-related errors early in the development process, reducing runtime errors and enhancing code reliability. By enforcing type consistency, developers can maintain a more predictable and maintainable codebase.

2. What is MyPy

MyPy Overview

MyPy is a static type checker for Python that verifies the type correctness of code based on type annotations. It integrates seamlessly with modern Python workflows, providing immediate feedback on type-related issues and ensuring that the code adheres to the specified type contracts. MyPy supports Python versions up to 3.10, enabling the use of the latest language features.

3. Coding Standards Using MyPy

MyPy Coding Standards

  • Python Version: Python 3.10 to leverage the latest language features and type annotations.
  • Strictness:
  • Disallow Untyped Definitions: All function and method definitions must include type annotations.
  • Disallow Untyped Calls: Function and method calls must match the type annotations of their definitions.
  • Ignore Missing Imports: Prevents false positives by ignoring imports that are not found, especially useful for dynamic or optional dependencies.
  • File Types Included: .py, .pyi, and pyproject.toml to ensure type consistency across Python scripts, type hint files, and configuration files.

4. How MyPy Has Been Configured and Where

MyPy Configuration
pyproject.toml
[tool.poetry.dev-dependencies]
mypy = "1.10.0"

[tool.mypy]
python_version = "3.10"
disallow_untyped_defs = true
disallow_untyped_calls = true
ignore_missing_imports = true
.vscode/settings.json
{
    "mypy-type-checker.args": [
        "--config-file=pyproject.toml"
    ],
    "mypy-type-checker.cwd": "${workspaceFolder}",
    "mypy-type-checker.importStrategy": "fromEnvironment",
    "mypy-type-checker.preferDaemon": true,
    "mypy-type-checker.reportingScope": "workspace",
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnSave": false
    },
    "mypy-type-checker.enable": true
}
.vscode/extensions.json
{
    "recommendations": [
        "ms-python.python",
        "donjayamanne.python-environment-manager",
        "mypy-type-checker"
        // other extensions...
    ]
}

5. How MyPy Has Been Enforced

Enforcement Notice

Enforcement: - Pre-commit Hooks: Integrated into pre-commit via the mypy hook, ensuring that all committed code adheres to the defined type standards and catches type-related issues before merging. - Editor Integration: Configured in VSCode with the mypy-type-checker extension, providing real-time type checking and feedback as developers write code.

.pre-commit-config.yaml
- repo: https://github.com/pre-commit/mirrors-mypy
  rev: v1.10.0
  hooks:
    - id: mypy
      args:
        - --config-file=pyproject.toml

Input Validation

1. Why We Use Input Validation

Purpose of Input Validation

Input validation ensures that the data entering the application adheres to expected formats and types. This practice enhances data integrity, prevents runtime errors, and safeguards against malicious inputs. By validating inputs rigorously, we maintain the reliability and security of the application.

2. What is Pydantic

Pydantic Overview

Pydantic is a powerful Python library for data validation and settings management using Python type annotations. It enforces type hints at runtime, ensuring that data conforms to the defined models. Pydantic streamlines the process of parsing and validating complex data structures, making the codebase more robust and maintainable.

3. Coding Standards Using Pydantic

Pydantic Coding Standards

  • Data Models: Define all data models by inheriting from pydantic.BaseModel.
  • Type Annotations: Utilize Python type annotations to specify the expected types for each field.
  • Field Constraints: Apply pydantic validators and constraints (e.g., Field(..., min_length=1)) to enforce data integrity.
  • Immutability: Use immutable models (Config.allow_mutation = False) where appropriate to prevent unintended modifications.
  • Documentation: Include comprehensive docstrings for all models and fields to enhance readability and maintainability.

4. How Pydantic Has Been Configured and Where

Pydantic Configuration
pyproject.toml
[tool.poetry.dependencies]
pydantic = "2.8.2"
.vscode/settings.json
{
    "mypy-type-checker.args": [
        "--config-file=pyproject.toml"
    ],
    "mypy-type-checker.cwd": "${workspaceFolder}",
    "mypy-type-checker.importStrategy": "fromEnvironment",
    "mypy-type-checker.preferDaemon": true,
    "mypy-type-checker.reportingScope": "workspace",
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnSave": false
    },
    "mypy-type-checker.enable": true
}
.vscode/extensions.json
{
    "recommendations": [
        "mypy-type-checker",
        "ms-python.python",
        "donjayamanne.python-environment-manager"
        // other extensions...
    ]
}

5. How Pydantic Has Been Enforced

Enforcement Notice

Enforcement: - Pre-commit Hooks: Integrated into pre-commit via the mypy hook, ensuring that all Pydantic models adhere to the defined type annotations and validation rules before any code is committed. - Editor Integration: Configured in VSCode with the mypy-type-checker extension, providing real-time type checking and feedback as developers write code.

.pre-commit-config.yaml
- repo: https://github.com/pre-commit/mirrors-mypy
  rev: v1.10.0
  hooks:
    - id: mypy
      args:
        - --config-file=pyproject.toml

Testing

1. Why We Use a Test Framework

Purpose of Test Frameworks

A test framework like Pytest automates the process of verifying that code functionalities work as intended. Implementing a test framework ensures that new changes do not break existing functionalities, facilitates continuous integration, and promotes a reliable and maintainable codebase. By systematically testing code, we can identify and address issues early in the development cycle, enhancing overall software quality.

2. What is Pytest

Pytest Overview

Pytest is the designated testing framework used in the cookiecutter-collabora template. It provides a robust and flexible platform for writing and running tests, supporting fixtures, parameterized testing, and a rich ecosystem of plugins. Pytest simplifies the testing process, making it easier to write readable and maintainable tests that ensure the correctness of the codebase.

3. Coding Standards Using Pytest

Pytest Coding Standards

  • Test Paths: All tests are located in the tests/ directory to maintain a clear separation between production code and tests.
  • Coverage:
  • Source Directory: Coverage reports are generated for the src/{{cookiecutter.package_name}} directory to ensure comprehensive testing of the core functionality.
  • Omissions: Specific files and directories are omitted from coverage metrics to exclude irrelevant or non-essential components.
  • Options:
  • Verbose Output: Enabled to provide detailed test execution information.
  • Coverage Reports: Generated in both terminal and HTML formats for easy analysis.
  • Test Timeout: Set to 5 seconds to prevent long-running tests from blocking the development process.
  • File Naming Conventions:
  • Test Files: Prefixed with test_ (e.g., test_module.py) to clearly identify test modules.
  • Test Classes: Prefixed with Test (e.g., TestUserModel) to denote test classes.
  • Test Functions: Prefixed with test_ (e.g., test_add_user) to specify individual test cases.

4. How Pytest Has Been Configured and Where

Pytest Configuration
pyproject.toml
[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]
addopts = "-v --cov=src/{{cookiecutter.package_name}} --cov-report=term-missing --cov-report=html --timeout=5"
python_files = "test_*.py"
python_classes = "Test*"
python_functions = "test_*"
log_cli = true
log_cli_level = "INFO"
log_format = "%(asctime)s %(levelname)s %(message)s"
log_date_format = "%Y-%m-%d %H:%M:%S"
.vscode/settings.json
{
    "mypy-type-checker.args": [
        "--config-file=pyproject.toml"
    ],
    "mypy-type-checker.cwd": "${workspaceFolder}",
    "mypy-type-checker.importStrategy": "fromEnvironment",
    "mypy-type-checker.preferDaemon": true,
    "mypy-type-checker.reportingScope": "workspace",
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnSave": false
    },
    "mypy-type-checker.enable": true
}
.vscode/extensions.json
{
    "recommendations": [
        "mypy-type-checker",
        "ms-python.python",
        "donjayamanne.python-environment-manager"
        // other extensions...
    ]
}

5. How Pytest Has Been Enforced

Enforcement Notice

Enforcement: - Pre-commit Hooks: Integrated into pre-commit via the pytest hook, ensuring that tests are run before commits are finalized.

.pre-commit-config.yaml
- repo: local
  hooks:
    - id: pytest
      name: Run PyTest
      entry: pytest
      language: system
      types: [python]
      stages: [pre-commit, pre-push]

Docstrings

1. Why We Use Docstrings

Purpose of Docstrings

Docstrings provide essential documentation within the codebase, enhancing clarity, readability, and maintainability. By adhering to a consistent docstring format, all contributors can easily understand and utilize the code components, facilitating better collaboration and reducing the learning curve for new team members.

2. What are Google Style Docstrings

Google Style Docstrings Overview

We utilize the Google Style for all docstrings within the cookiecutter-collabora template. This style promotes readability and consistency, making it easier for developers to document and comprehend functions, classes, and modules.

3. Coding Standards Using Google Style Docstrings

Google Docstring Coding Standards

  • Format: Follows the Google Python Style Guide.
  • Scope: Applies to all public modules, functions, classes, and methods.
  • Components:
  • Short Description: A brief summary of the object's purpose.
  • Args: Description of each parameter, including type annotations.
  • Returns: Description of the return value and its type.
  • Raises: Exceptions that the function may raise.

4. How Docstrings Have Been Configured and Where

Docstring Configuration
pyproject.toml
[tool.pydocstyle]
convention = "google"
add-ignore = ["D100"]  # Example: Ignore missing docstrings for private modules
.vscode/settings.json
{
    "autoDocstring.docstringFormat": "google",
    "autoDocstring.includeExtendedSummary": true,
    "autoDocstring.includeName": false
}
.vscode/extensions.json
{
    "recommendations": [
        "njpwerner.autodocstring",
        // other extensions...
    ]
}

5. How Docstrings Have Been Enforced

Enforcement Notice

Enforcement: - Pre-commit Hooks: Automatically checks docstring compliance on pre-commit via the pydocstyle hook, ensuring that all committed code adheres to the Google docstring standards. - Editor Integration: Configured in VSCode with the autoDocstring extension set to Google style, providing real-time docstring generation and validation as developers write code.

.pre-commit-config.yaml
- repo: https://github.com/pre-commit/mirrors-pydocstyle
  rev: v6.1.1
  hooks:
    - id: pydocstyle
      args: [--config=pyproject.toml]

Comment Length Standards

1. Why We Use Comment Length Standards

Purpose of Comment Length Standards

Comment length standards ensure that comments remain readable and do not disrupt the flow of the code. By limiting comments to a maximum of 79 characters per line, we maintain consistency across the codebase, enhance readability, and facilitate easier code reviews. Clear and concise comments help developers understand the purpose and functionality of code segments without unnecessary verbosity.

2. What are Comment Length Standards

Comment Length Standards Overview

Comment length standards dictate the maximum allowable length for comments within the code. Adhering to these standards helps in:

  • Readability: Shorter comments are easier to read and understand.
  • Consistency: Uniform comment lengths prevent inconsistencies that can arise from varying comment styles.
  • Maintainability: Clear and concise comments make the codebase easier to maintain and update.

3. Coding Standards for Comment Length

Comment Length Coding Standards

  • Maximum Length: Comments should not exceed 79 characters per line to maintain readability across various editors and interfaces.
  • Clarity: Ensure comments are clear and concise, explaining the purpose rather than stating the obvious.
  • Consistency: Maintain uniform comment formatting throughout the codebase, such as using a single space after the # symbol.
  • Single vs. Multi-line Comments: Use single-line comments for brief explanations and multi-line comments for more detailed descriptions, ensuring each line adheres to the length limit.

4. How Comment Length Standards Have Been Configured and Where

Comment Length Configuration
pyproject.toml
[tool.ruff]
select = [
    # Pyflakes (F) rules
    "F401", "F402", "F403", "F405", "F601", "F602", "F621", "F631",
    "F632", "F701", "F702", "F704", "F706", "F707", "F722",
    "F811", "F821", "F841",
    # pycodestyle (E, W) rules
    "E101", "E111", "E112", "E113", "E114", "E115", "E116",
    "E117", "E201", "E202", "E203", "E211", "E225", "E231",
    "E251", "E261", "E262", "E265", "E266", "E271", "E272",
    "E273", "E274", "E275", "E401", "E402", "E501",
    "E711", "E712", "E713", "E714", "E721", "E722", "E731",
    # isort (I) rules
    "I001", "I002",
    # pep8-naming (N) rules
    "N801", "N802", "N803", "N804", "N805", "N806",
    # pydocstyle (D) rules
    "D100", "D101", "D102", "D103", "D104", "D105",
    "D106", "D107",
]
line-length = 79
include = ["*.py", "*.pyi", "**/pyproject.toml", "*.ipynb"]
.vscode/settings.json
{
    "ruff.args": [
        "--config=pyproject.toml",
        "--preview"
    ],
    "ruff.path": [
        "/bin/ruff"
    ],
    "ruff.interpreter": [
        "/bin/python"
    ],
    "editor.rulers": [
        72,
        79
    ],
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnSave": false
    },
    "charliermarsh.ruff.enable": true
}
.vscode/extensions.json
{
    "recommendations": [
        "charliermarsh.ruff",
        "ms-python.black-formatter",
        // other extensions...
    ]
}

5. How Comment Length Standards Have Been Enforced

Enforcement Notice

Enforcement: - Pre-commit Hooks: Integrated into pre-commit via the ruff hook, ensuring that all comments adhere to the defined length and formatting standards before any code is committed. - Editor Integration: Configured in VSCode with linting extensions that highlight overly long comments, providing real-time feedback to developers as they write code.

.pre-commit-config.yaml
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.4.9
  hooks:
    - id: ruff
      name: ruff-linter
      types_or: [python, pyi, jupyter]
      args: ["--config=pyproject.toml", "--fix", "--preview"]

Version Control Standards

1. Why We Use Version Control Standards

Purpose of Version Control Standards

Consistent version control practices enhance clarity and streamline collaboration among team members. By adhering to standardized branch naming and commit message conventions, we facilitate easier tracking of changes, improve codebase organization, and reduce misunderstandings during development and code reviews.

2. Branch Naming Conventions

Branch Naming Importance

Consistent branch naming enhances clarity and streamlines collaboration.

  • Pattern: <category>/<description>-<JIRA_KEY>[-subtask-<number>]
  • Categories: feature, bugfix, data, experiment, model, docs, refactor, test, chore, hotfix, performance, security, build, ci, hyperparameter-tuning, preprocessing, deployment, visualization, evaluation
  • Exceptions: dev, production, main

Enforcement Tips

Enforcement: - Checked via branch-name-check.sh pre-commit hook. - Non-compliant branches are deleted automatically.

3. Commit Message Standards

Commit Message Importance

Clear and descriptive commit messages facilitate understanding of code changes.

  • Pattern: Incorporate <JIRA_KEY> and descriptive text.
  • Example: fix: resolve DATA-123 user authentication bug

Commit Message Enforcement

Enforcement: - Validated via commit-msg-check.sh pre-commit hook. - Ensures commit messages adhere to the defined pattern.

4. How Version Control Standards Have Been Configured and Where

Version Control Configuration
scripts/hooks/branch-name-check.sh
#!/bin/sh

# Define the regex pattern for branch names
BRANCH_NAME_REGEX="^(feature|bugfix|data|experiment|model|docs|refactor|test|chore|hotfix|performance|security|build|ci|hyperparameter-tuning|preprocessing|deployment|visualization|evaluation)\/[a-z0-9-]+-[A-Z]+-[0-9]+(-subtask-[0-9]+)?$"

# Get the current branch name
BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)

# Define exceptions for branch names
EXCEPTIONS=("dev" "production" "main")

# Check if the branch name is an exception
is_exception() {
  for exception in "${EXCEPTIONS[@]}"; do
    if [ "$BRANCH_NAME" = "$exception" ]; then
      return 0
    fi
  done
  return 1
}

# Check if this is a branch creation (args: 1 for new branch creation, 0 otherwise)
if [ "$3" = "1" ]; then
  # If the branch name is an exception, skip the pattern check
  if is_exception; then
    exit 0
  fi

  # Check if the branch name matches the expected pattern
  if ! echo "$BRANCH_NAME" | grep -qE "$BRANCH_NAME_REGEX"; then
    echo "Error: Branch name must follow the pattern '<category>/<description>-<JIRA_KEY>'"
    echo "Example: feature/user-authentication-DATA-123"
    echo "Deleting branch: $BRANCH_NAME"
    git checkout -
    git branch -D "$BRANCH_NAME"
    exit 1
  fi
fi
scripts/hooks/commit-msg-check.sh
#!/bin/sh

# Define the regex pattern for commit messages
COMMIT_MSG_REGEX="^(feat|fix|docs|style|refactor|test|chore): .+-[A-Z]+-[0-9]+( -subtask-[0-9]+)?$"

# Get the commit message
COMMIT_MSG=$(cat "$1")

# Check if the commit message matches the pattern
if ! echo "$COMMIT_MSG" | grep -qE "$COMMIT_MSG_REGEX"; then
  echo "Error: Commit message must follow the pattern '<type>: <description>-<JIRA_KEY>[-subtask-<number>]'"
  echo "Example: fix: resolve DATA-123 user authentication bug"
  exit 1
fi

exit 0
scripts/hooks/filename-check.sh
#!/bin/bash

# Regex pattern for snake_case filenames
SNAKE_CASE_REGEX='^[a-z0-9_]+(\.py|\.ipynb|\.md|\.csv|\.json|\.jsonl)$'

# List of allowed filenames that do not follow snake_case
ALLOWED_FILENAMES=("README.md" "CONTRIBUTING.md" "__init__.py")

# List of directories to inspect
DIRECTORIES_TO_INSPECT=("src/" "tests/" "notebooks/")

# Get the list of files to be committed
files_to_check=$(git diff --cached --name-only)

# Function to check if a filename is in the allowed list
is_allowed_filename() {
  local filename=$1
  for allowed in "${ALLOWED_FILENAMES[@]}"; do
    if [[ $filename == $allowed ]]; then
      return 0
    fi
  done
  return 1
}

# Function to check if a file is in the directories to inspect
is_in_inspected_directory() {
  local file=$1
  for directory in "${DIRECTORIES_TO_INSPECT[@]}"; do
    if [[ $file == $directory* ]]; then
      return 0
    fi
  done
  return 1
}

# Check each file
for file in $files_to_check; do
  if is_in_inspected_directory "$file" && [[ $file =~ \.py$|\.ipynb$|\.md$|\.csv$|\.json$|\.jsonl$ ]]; then
    filename=$(basename "$file")
    if ! is_allowed_filename "$filename" && ! [[ $filename =~ $SNAKE_CASE_REGEX ]]; then
      echo "Error: Filename '$filename' in '$file' does not follow the snake_case naming convention."
      exit 1
    fi
  fi
done

# If no issues, exit with status 0
exit 0

5. How Version Control Standards Have Been Enforced

Enforcement Notice

Enforcement: - Pre-commit Hooks: Integrated into pre-commit via the branch-name-check.sh, commit-msg-check.sh, and filename-check.sh hooks, ensuring that branch names, commit messages, and filenames adhere to the defined standards before any code is committed. - Automated Validation: The pre-commit hooks automatically validate branch names, commit messages, and filenames, preventing non-compliant code from being merged into the codebase.

.pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: branch-name-check
        name: Branch Name Check
        entry: scripts/hooks/branch-name-check.sh
        language: script
        stages: [pre-commit]
      - id: commit-msg-check
        name: Commit Message Check
        entry: scripts/hooks/commit-msg-check.sh
        language: script
        stages: [commit-msg]
      - id: filename-check
        name: Filename Snake Case Check
        entry: scripts/hooks/filename-check.sh
        language: script
        stages: [pre-commit]

Gitignore Standards

1. Why We Use .gitignore

Importance of .gitignore

Properly configuring .gitignore ensures that unnecessary or sensitive files are excluded from version control, maintaining repository cleanliness and security. By ignoring files such as build artifacts, environment configurations, and temporary files, we prevent cluttering the repository with irrelevant or potentially sensitive information.

2. What is .gitignore

gitignore Overview

The .gitignore file specifies intentionally untracked files that Git should ignore. Files already tracked by Git are not affected. By defining patterns in .gitignore, we can ensure that certain files or directories are excluded from version control, streamlining the repository and focusing on the essential code and resources.

3. Coding Standards Using .gitignore

gitignore Coding Standards

  • Data Files: Exclude common data file formats (.csv, .json, .xlsx, etc.) globally, with specific directories for raw, processed, external, interim, and feature data.
  • Image, Video, Audio Files: Exclude common multimedia formats globally.
  • Environment Files: Exclude virtual environments (.env, .venv, etc.) and configuration files.
  • Operating System Files: Exclude OS-specific files like .DS_Store for macOS.
  • Tool-specific Files: Exclude files related to Python packaging (__pycache__, .mypy_cache/, etc.), documentation builds (docs/_build/), and editor configurations (.vscode/).
  • Exceptions: Maintain tracking for specific placeholder files using negation patterns (e.g., !data/processed/.gitkeep).

4. How .gitignore Has Been Configured and Where

Gitignore Configuration
.gitignore
## Ignore Data Files ##

## Ignore data files globally ##
*.csv
**/*.csv
*.json
**/*.json
*.xls
**/*.xls
*.xlsx
**/*.xlsx
*.parquet
**/*.parquet
*.hdf5
**/*.hdf5
*.h5
**/*.h5
*.feather
**/*.feather
*.pickle
**/*.pickle
*.pkl
**/*.pkl
*.xml
**/*.xml
*.xml
**/*.xml

## Ignore image files globally ##
*.png
**/*.png
*.jpg
**/*.jpg
*.jpeg
**/*.jpeg
*.bmp
**/*.bmp
*.gif
**/*.gif
*.tiff
**/*.tiff

## Ignore video files globally ##
*.mp4
**/*.mp4
*.avi
**/*.avi
*.mov
**/*.mov
*.mkv
**/*.mkv
*.flv
**/*.flv
*.wmv
**/*.wmv

## Ignore audio files globally ##
*.wav
**/*.wav
*.mp3
**/*.mp3
*.flac
**/*.flac
*.aac
**/*.aac

## Data Directories ##

# Ignore any data in the following directories
data/processed/*
data/raw/*
data/external/*
data/interim/*
data/features/*

# But keep tracking these specific files (if needed)
!data/processed/.gitkeep
!data/raw/.gitkeep
!data/external/.gitkeep
!data/interim/.gitkeep
!data/features/.gitkeep

## macOS ##

.DS_Store
**/.DS_Store

## Gitignore Standards

Documentation Standards

1. Why We Use a Documentation Framework

Purpose of Documentation Frameworks

A documentation framework like MkDocs ensures that all aspects of the project are well-documented and easily accessible. Proper documentation enhances clarity, facilitates onboarding of new team members, and provides a reliable reference for existing contributors. By adhering to a consistent documentation structure, we promote maintainability and improve overall project quality.

2. What is MkDocs

MkDocs Overview

MkDocs is a static site generator specifically designed for project documentation. It allows developers to write documentation in Markdown and generates a clean, responsive website that is easy to navigate. MkDocs supports various themes and plugins, enabling customization to meet the project's specific needs.

3. Coding Standards Using MkDocs

MkDocs Coding Standards

  • Theme: Utilize the Material theme for a modern and responsive design.
  • Plugins: Incorporate essential plugins such as:
    • mkdocstrings for API documentation.
    • mermaid2 for diagram generation.
    • git-revision-date-localized for displaying the last revision date.
  • Markdown Extensions: Enable the following extensions to enhance documentation capabilities:
    • Admonitions for callouts.
    • Details for collapsible sections.
    • Superfences for enhanced code block support.
    • Inline highlights for emphasizing text.
    • Snippets for reusable content.
    • Emojis for visual cues.
    • Task lists for tracking items.
  • Navigation Structure:
    • Home: Overview and introduction.
    • Tutorials: Step-by-step guides.
    • How-To Guides: Practical instructions for specific tasks.
    • API Reference: Detailed API documentation.
    • Explanation: In-depth explanations of concepts and implementations.
  • Extra Assets: Incorporate custom JavaScript and CSS to extend functionality and improve styling as needed.

4. How MkDocs Has Been Configured and Where

MkDocs Configuration Example

Configuration:

mkdocs.yml
site_name: {{cookiecutter.site_name}}

theme:
  name: "material"
  logo: assets/logo.png
  icon:
    repo: simple/github
  palette:
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/link
        name: Switch to light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/toggle-switch
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: indigo
      toggle:
        icon: material/toggle-switch-off
        name: Switch to system preference
  font:
    text: Roboto
    code: Roboto Mono
  features:
    - content.code.annotate

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - attr_list
  - md_in_html
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.arithmatex:
      generic: true
  - abbr
  - footnotes
  - toc:
      permalink: true
      title: On this page
  - tables
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true

plugins:
  - mkdocstrings
  - mermaid2
  - git-revision-date-localized:
      fallback_to_build_date: true

extra_javascript:
  - https://unpkg.com/mermaid/dist/mermaid.min.js
  - javascripts/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
extra_css:
  - stylesheets/extra.css

nav:
  - Home: index.md
  - Tutorials: tutorials.md
  - How-To Guides: how-to-guides.md
  - API Reference: api-reference.md
  - Explanation: explanation.md

Conclusion

Template Success

The cookiecutter-collabora template embodies a robust set of coding standards designed to promote consistency, quality, and efficiency in Python project development. By leveraging a suite of tools and meticulously configured settings, these standards are both implicitly and explicitly enforced, ensuring that all contributors adhere to best practices.

Adherence Benefits

Adhering to this Coding Standards Document will facilitate seamless collaboration, enhance code maintainability, and uphold the integrity of the project throughout its lifecycle. Developers are encouraged to familiarize themselves with these standards and integrate them into their workflow to maximize the benefits of this structured approach.