RadioWeb Docs

Appearance

Coding Norms ​

This document outlines the coding standards and best practices for the RadioWeb Education project.

General Rules ​

  • Code must be written in English
  • Code comments must be written in English only
  • Code must follow the standard naming conventions of each programming language used
  • Code must follow the best practices of each selected framework
  • Code must be divided into independent modules

TypeScript ​

  • Use .tsx for source files when relevant to React UI code, .ts for other TypeScript files.
  • Use .spec.ts for TypeScript test files and .spec.tsx for TSX component tests
  • Use TypeScript for all new code. Strict mode is enabled (strict: true in tsconfig.json)
  • Always provide explicit type annotations for function parameters and return types
  • Avoid using any type; use generics or union types instead
  • Use const/let over var
  • Use arrow functions for callbacks and shorter functions, regular functions for constructors

Naming Conventions ​

  • Folders must use kebab-case (example: case-detail-view)
  • TSX and general file names should use kebab-case (example: user-profile-card.tsx)
  • Class names and React component names must use PascalCase (example: UserProfileCard)

Code Style ​

  • ESLint configuration is enforced on all commits
  • Code must follow linter recommendations
  • Maximum line length: 100 characters
  • Indentation: 2 spaces
  • Use single quotes for strings (except for template literals)
  • Add trailing commas in multi-line structures

Run the linter before committing:

bash
npm run lint
npm run lint:fix  # Auto-fix issues

Testing ​

  • All new features must include automated tests
  • Use Vitest for the backend test framework
  • Maintain a minimum statement coverage of 70%
  • Test files should be co-located with their source files using .spec.tsx suffix for TSX components
  • Use descriptive test names following the pattern: "should [expected behavior] when [condition]"

Run tests before committing:

bash
npm run test
npm run test:coverage       # With coverage report

Backend ​

  • Use tsoa decorators for API endpoint documentation

WARNING

As much as possible, use the right HTTP verb, such as PATCH for modifying a ressource, because tsoa changes its behaviour depending on the HTTP verb decorator used.

  • Organize code by feature in controllers/services/dtos structure
  • Always validate input using DTOs and decorators
  • Use meaningful HTTP status codes (e.g., 201 for created, 422 for validation errors)

Frontend ​

  • Keep components small and focused (single responsibility principle)
  • Use kebab-case for component file names and PascalCase for component symbols

Git Workflow ​

  • Create feature branches from main with descriptive names: feature/user-authentication, fix/dicom-upload-bug
  • Commit messages should be clear and concise:
    • Example: feat: add DICOM viewer to case detail page
    • Use conventional commits: feat:, fix:, docs:, test:, refactor:
  • Push commits regularly and open a pull request for review
  • Ensure all CI checks pass before merging

Documentation ​

  • Document complex logic with clear comments
  • Keep README files up to date
  • Update API documentation (Swagger) via tsoa decorators
  • Write meaningful commit messages and PR descriptions

Database & Migrations ​

  • Use TypeORM for database operations

Environment Variables ​

  • Never commit sensitive information (API keys, database passwords)