Code Style Guidelines

CVAT follows strict coding standards to maintain code quality and consistency across the project. This guide covers the style guidelines for different programming languages used in CVAT.

General Principles

Write readable code: Code is read more often than written
Be consistent: Follow existing patterns in the codebase
Document your code: Add comments for complex logic
Keep it simple: Avoid unnecessary complexity
Test your changes: Ensure code works as expected

Python Code Style

CVAT’s Python code follows PEP 8 with some modifications enforced by Black and isort.

Formatters and Linters

Black

Black is used for automatic code formatting with these settings:

[tool.black]
line-length = 100
target-version = ['py310']

Format your Python code:

black cvat/

isort

Isort organizes imports with Black-compatible settings:

[tool.isort]
profile = "black"
line_length = 100
forced_separate = ["tests"]

Sort imports:

isort cvat/

pylint

Pylint is used for static code analysis. Run it to check for issues:

pylint cvat/

Python Style Guidelines

Line length: Maximum 100 characters
Indentation: 4 spaces (no tabs)
Imports: Group imports (standard library, third-party, local) and sort alphabetically
Naming conventions:
- Classes: PascalCase
- Functions and variables: snake_case
- Constants: UPPER_SNAKE_CASE
- Private members: _leading_underscore

Example

from typing import List, Optional

import django
from rest_framework import serializers

from cvat.apps.engine.models import Task


class TaskSerializer(serializers.ModelSerializer):
    """Serializer for Task model with custom validation."""

    def validate_name(self, value: str) -> str:
        """Validate that task name is not empty."""
        if not value.strip():
            raise serializers.ValidationError("Task name cannot be empty")
        return value

    class Meta:
        model = Task
        fields = "__all__"

JavaScript/TypeScript Code Style

The frontend uses ESLint and Prettier for code quality and formatting.

ESLint Configuration

CVAT uses a strict ESLint configuration based on Airbnb style guide:

// Key rules
{
  "indent": ["error", 4],
  "max-len": ["error", { "code": 120 }],
  "quotes": ["error", "single"],
  "semi": ["error", "always"]
}

Prettier Configuration

Prettier enforces consistent formatting:

{
  "printWidth": 120,
  "tabWidth": 4,
  "singleQuote": true,
  "semi": true,
  "trailingComma": "all",
  "arrowParens": "always",
  "jsxSingleQuote": true
}

Running Linters

Check code style:

# ESLint
yarn run lint

# Prettier
yarn run prettier --check .

Auto-fix issues:

# ESLint
yarn run lint --fix

# Prettier
yarn run prettier --write .

TypeScript/JavaScript Style Guidelines

Line length: Maximum 120 characters
Indentation: 4 spaces
Quotes: Single quotes for strings, JSX props use single quotes
Semicolons: Always required
Naming conventions:
- Interfaces/Types: PascalCase
- Functions/Variables: camelCase
- Constants: UPPER_SNAKE_CASE
- React components: PascalCase
- Private members: _leadingUnderscore

TypeScript Example

import React from 'react';
import { Task } from 'cvat-core-wrapper';

interface TaskItemProps {
    task: Task;
    onSelect: (taskId: number) => void;
}

export default function TaskItem({ task, onSelect }: TaskItemProps): JSX.Element {
    const handleClick = (): void => {
        onSelect(task.id);
    };

    return (
        <div className='task-item' onClick={handleClick}>
            <h3>{task.name}</h3>
            <p>{task.status}</p>
        </div>
    );
}

File Organization

Python Files

# Copyright header
# SPDX-License-Identifier: MIT

"""Module docstring describing the file purpose."""

# Standard library imports
import os
import sys

# Third-party imports
import django
from rest_framework import viewsets

# Local imports
from cvat.apps.engine.models import Task

# Constants
MAX_RETRY_COUNT = 3

# Module code

TypeScript/JavaScript Files

// Copyright (C) CVAT.ai Corporation
// SPDX-License-Identifier: MIT

// External imports
import React from 'react';
import { useSelector } from 'react-redux';

// CVAT imports
import { Task } from 'cvat-core-wrapper';

// Local imports
import './styles.scss';

// Constants
const MAX_ITEMS_PER_PAGE = 10;

// Component code

Comments and Documentation

Python Docstrings

Use Google-style docstrings:

def create_task(name: str, owner_id: int, labels: List[str]) -> Task:
    """Create a new annotation task.

    Args:
        name: The task name
        owner_id: ID of the task owner
        labels: List of label names

    Returns:
        The created Task instance

    Raises:
        ValidationError: If task name is invalid
    """
    pass

TypeScript/JSDoc Comments

/**
 * Calculate the annotation completion percentage
 * @param completed - Number of completed frames
 * @param total - Total number of frames
 * @returns Percentage value between 0 and 100
 */
function calculateProgress(completed: number, total: number): number {
    return (completed / total) * 100;
}

Git Commit Messages

Write clear, descriptive commit messages:

Short summary (50 chars or less)

Detailed explanation of the changes if needed. Wrap at 72 characters.
Explain the problem this commit solves and why this approach was chosen.

- Use bullet points for multiple changes
- Reference issues: Fixes #123, Resolves #456
- Break lines at 72 characters

Good commit message examples:

Fix annotation export for rotated bounding boxes
Add support for video chapters in frame navigation
Refactor task creation to improve performance
Update dependencies to fix security vulnerabilities

Pre-commit Hooks

CVAT uses linters in CI/CD. Before committing, run:

# Python
black cvat/
isort cvat/
pylint cvat/

# JavaScript/TypeScript
yarn run lint --fix
yarn run prettier --write .

Code Review Guidelines

When reviewing code:

Check for adherence to style guidelines
Verify tests are included and passing
Look for potential bugs or edge cases
Ensure code is readable and maintainable
Provide constructive feedback
Approve when requirements are met

Security Considerations

ESLint includes security plugins:

plugins: ['security', 'no-unsanitized']

Always:

Sanitize user input
Avoid eval() and similar dangerous functions
Use parameterized queries for database access
Validate and escape data before rendering

Editor Configuration

VS Code

Recommended extensions:

Python (Microsoft)
Pylance
ESLint
Prettier
EditorConfig

Settings:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "python.formatting.provider": "black",
  "python.linting.pylintEnabled": true
}

PyCharm/WebStorm

Configure:

Black as the Python formatter
ESLint for JavaScript/TypeScript
Prettier for auto-formatting
Line length to 100 (Python) or 120 (JS/TS)

Continuous Integration

CVAT’s CI runs these checks on every pull request:

Linters: ESLint, Pylint, Black, isort
Type checking: TypeScript compiler, mypy
Security: CodeQL analysis
Tests: Unit, integration, and E2E tests

Ensure your code passes all checks before submitting a PR.

Next Steps

Learn about testing your changes
Understand the system architecture
Read the pull request guide

Development

Resources

Code Style Guidelines

General Principles

Python Code Style

Formatters and Linters

Black

isort

pylint

Python Style Guidelines

Example

JavaScript/TypeScript Code Style

ESLint Configuration

Prettier Configuration

Running Linters

TypeScript/JavaScript Style Guidelines

TypeScript Example

File Organization

Python Files

TypeScript/JavaScript Files

Comments and Documentation

Python Docstrings

TypeScript/JSDoc Comments

Git Commit Messages

Pre-commit Hooks

Code Review Guidelines

Security Considerations

Editor Configuration

VS Code

PyCharm/WebStorm

Continuous Integration

Next Steps

Build docs developers (and LLMs) love

Development

Resources

Documentation Index

​General Principles

​Python Code Style

​Formatters and Linters

​Black

​isort

​pylint

​Python Style Guidelines

​Example

​JavaScript/TypeScript Code Style

​ESLint Configuration

​Prettier Configuration

​Running Linters

​TypeScript/JavaScript Style Guidelines

​TypeScript Example

​File Organization

​Python Files

​TypeScript/JavaScript Files

​Comments and Documentation

​Python Docstrings

​TypeScript/JSDoc Comments

​Git Commit Messages

​Pre-commit Hooks

​Code Review Guidelines

​Security Considerations

​Editor Configuration

​VS Code

​PyCharm/WebStorm

​Continuous Integration

​Next Steps

Build docs developers (and LLMs) love

General Principles

Python Code Style

Formatters and Linters

Black

isort

pylint

Python Style Guidelines

Example

JavaScript/TypeScript Code Style

ESLint Configuration

Prettier Configuration

Running Linters

TypeScript/JavaScript Style Guidelines

TypeScript Example

File Organization

Python Files

TypeScript/JavaScript Files

Comments and Documentation

Python Docstrings

TypeScript/JSDoc Comments

Git Commit Messages

Pre-commit Hooks

Code Review Guidelines

Security Considerations

Editor Configuration

VS Code

PyCharm/WebStorm

Continuous Integration

Next Steps