Conventions

Coding Conventions Skill

Overview

This skill centralizes general coding conventions and best practices that apply across multiple technologies and frameworks. It covers code organization, documentation, naming, and type import strategies.

Objective

Ensure consistent coding practices across the codebase regardless of technology stack. This skill delegates technology-specific conventions to their respective skills (e.g., TypeScript, React, MUI).

When to Use

Use this skill when:

• Establishing general code organization patterns
• Defining naming conventions across technologies
• Setting up documentation standards
• Creating project structure guidelines
• Reviewing code for general best practices

Don't use this skill for:

• Technology-specific patterns (use typescript, react, etc.)
• Accessibility rules (use a11y skill)
• Framework-specific conventions (use framework skill)
• Architecture patterns (use architecture-patterns when project already uses SOLID, Clean Architecture, DDD)

Critical Patterns

✅ REQUIRED: Consistent Naming Conventions

// ✅ CORRECT: Proper naming by type
const userId = 123; // camelCase for variables
function getUserData() {} // camelCase for functions
class UserService {} // PascalCase for classes
const MAX_RETRY_COUNT = 3; // UPPER_SNAKE_CASE for constants

// ❌ WRONG: Inconsistent naming
const UserID = 123; // Wrong case
function GetUserData() {} // Wrong case
class userService {} // Wrong case
const maxRetryCount = 3; // Wrong case for constant

✅ REQUIRED: Group and Organize Imports

// ✅ CORRECT: Grouped imports
// External libraries
import React from "react";
import { Button } from "@mui/material";

// Internal modules
import { UserService } from "./services/UserService";
import { formatDate } from "./utils/date";

// Types
import type { User } from "./types";

// ❌ WRONG: Random import order
import type { User } from "./types";
import { formatDate } from "./utils/date";
import React from "react";
import { Button } from "@mui/material";

✅ REQUIRED: Single Responsibility Principle

// ✅ CORRECT: Each file has one clear purpose
// UserService.ts - handles user operations
// UserValidator.ts - validates user data
// UserTypes.ts - defines user types

// ❌ WRONG: Everything in one file
// utils.ts - contains validation, API calls, formatting, types...

Conventions

Code Organization

• Group related imports together (external libraries, internal modules, types)
• Use consistent file/folder structure within projects
• Separate business logic from UI components
• Follow single responsibility principle for files and functions

Documentation

• Add JSDoc comments for exported functions, classes, and interfaces
• Document complex logic with inline comments
• Keep README files updated with setup instructions and architecture notes
• Use descriptive variable and function names that reduce need for comments

Naming

• Use camelCase for variables and functions
• Use PascalCase for classes and components
• Use UPPER_SNAKE_CASE for constants
• Use descriptive names that reveal intent

Type Imports

• Import types separately using import type when supported
• Keep type imports organized and grouped
• Avoid circular dependencies in type definitions

Decision Tree

New component or file? → Check naming conventions (camelCase/PascalCase/UPPER_SNAKE_CASE), place in appropriate directory structure.

Adding imports? → Group by category: external libraries first, internal modules second, types last. Use import type for TypeScript.

Complex logic? → Add inline comments for "why", not "what". Refactor if complexity exceeds file responsibility.

Naming unclear? → Use descriptive names that reveal intent. Avoid abbreviations unless widely known (e.g., userId OK, usrId not OK).

Cross-file logic? → Extract to shared utility/service. Avoid circular dependencies by separating interfaces from implementations.

Technology-specific convention? → Delegate to specific skill (typescript, react, mui, etc.). This skill only covers cross-technology patterns.

Documentation needed? → Add JSDoc for public APIs, inline comments for complex logic, update README for architectural changes.

Edge Cases

Abbreviations: Use well-known abbreviations (HTTP, API, URL, ID) but avoid custom ones. userId is OK, usrId is not.

Acronyms in names: Treat as words: HttpService not HTTPService, apiKey not aPIKey.

File naming: Match export name: UserService.ts exports UserService, index.ts for barrel exports.

Boolean naming: Use is, has, should prefixes: isActive, hasPermission, shouldRender.

Callback naming: Use handle or on prefix: handleClick, onSubmit.

References

• Individual technology skills for specific conventions
• Project-specific style guides