02_coding_style_guide

Coding Style Guide

A consistent coding style is crucial for readability and maintainability. We use automated tools to enforce our style guide.

General Principles

• Clarity over Brevity: Write code that is easy to understand, even if it’s slightly more verbose.
• DRY (Don’t Repeat Yourself): Avoid duplicating code. Use functions, components, and modules to create reusable abstractions.
• YAGNI (You Ain’t Gonna Need It): Don’t add functionality that you don’t need right now.

TypeScript / JavaScript

We follow modern TypeScript and JavaScript best practices.

• Linter: We use ESLint to enforce code quality and style rules.
• Formatter: We use Prettier for automated code formatting.
• Configuration: The specific ESLint and Prettier rules are defined in the .eslintrc.json and .prettierrc.json files in the root of each project. All developers should have their editors configured to format on save.

Key Style Points:

• Variables: Use const by default. Use let only when a variable needs to be reassigned. Avoid var.
• Naming:
  • Variables and Functions: camelCase (e.g., myVariable, calculateTotal).
  • Classes and Components: PascalCase (e.g., UserProfile, class DatabaseConnection).
  • Constants: UPPER_SNAKE_CASE for true constants (e.g., const API_KEY = '...').
• Imports:
  • Organize imports at the top of the file.
  • Group imports: 1. External libraries, 2. Internal modules, 3. CSS/assets.
  • Use absolute paths for imports from other directories within the project (@/components/Button instead of ../../components/Button).
• Functions:
  • Prefer arrow functions for anonymous functions and when you need to preserve the this context.
  • Keep functions small and focused on a single task.
• Types:
  • Use TypeScript for all new code.
  • Provide explicit types for function parameters and return values.
  • Use interfaces to define the shape of objects (interface User { ... }).

React

• Functional Components: Use functional components with hooks for all new components. Avoid class components.
• File Structure: Each component should be in its own file. For complex components, create a directory for the component and its related files (e.g., UserProfile/index.tsx, UserProfile/styles.css).
• State Management: For simple state, use the useState and useReducer hooks. For complex, shared state, use a dedicated state management library like Zustand or Redux Toolkit.
• JSX:
  • Use camelCase for HTML attributes (e.g., className, onClick).
  • Always include a key prop when rendering a list of elements.

HTML / CSS

• CSS-in-JS or CSS Modules: We prefer to scope styles to components using either CSS-in-JS (like Styled Components) or CSS Modules. This avoids global style conflicts.
• Naming: If using a global CSS methodology like BEM, follow the standard naming conventions.
• Accessibility (a11y):
  • Use semantic HTML5 tags (<nav>, <main>, <article>).
  • Ensure all interactive elements are accessible via keyboard.
  • Use alt tags for images.
  • Use ARIA attributes where necessary.

Tooling

• Pre-commit Hooks: We use Husky and lint-staged to automatically run ESLint and Prettier before each commit. This ensures that no un-styled code is pushed to the repository.
• VS Code Extensions: The following VS Code extensions are highly recommended:
  • ESLint
  • Prettier - Code formatter
  • EditorConfig for VS Code