## PHASE 5: Code Standards (15-20 min) > **Order for this phase:** 5.1 → 5.2 → 5.3 → 5.4 → 5.5 → 5.6 → 5.7 → 5.8 → 5.9 → 5.10 → 5.11 → 5.12 → 5.13 > **📌 Scope-based behavior:** > > - **MVP:** Ask 5.1-5.5 only (formatting, naming, structure, coverage target, Git workflow), skip 5.6-5.13 (advanced practices) > - **Production-Ready:** Ask all questions 5.1-5.13 > - **Enterprise:** Ask all questions 5.1-5.13 with emphasis on governance and documentation ### Objective Establish code quality rules, naming conventions, and development practices. --- ## 🔍 Pre-Flight Check (Smart Skip Logic) > 📎 **Reference:** See [prompts/shared/smart-skip-preflight.md](../../.ai-flow/prompts/shared/smart-skip-preflight.md) for the complete smart skip logic. **Execute Pre-Flight Check for Phase 5:** - **Target File**: `docs/code-standards.md` - **Phase Name**: "CODE STANDARDS" - **Key Items**: Linters, formatters, naming conventions, code review process - **Typical Gaps**: Team-specific conventions, code review workflow **Proceed with appropriate scenario based on audit data from `.ai-flow/cache/audit-data.json`** --- ## Phase 5 Questions (Full Mode) **5.1 Code Style & Formatting** ``` Formatting preferences: Indentation: A) ⭐ 2 spaces - Recommended for JavaScript/TypeScript B) 4 spaces - Common for Python, Java C) Tabs Quotes: A) ⭐ Single quotes - 'text' (JavaScript) B) Double quotes - "text" (Python, Java) Line length: A) ⭐ 80 characters - Traditional B) 100 characters - Modern balance C) 120 characters - Wide screens Semicolons (JavaScript/TypeScript): A) ⭐ Required - Always use semicolons B) Optional - ASI (Automatic Semicolon Insertion) Trailing commas: A) ⭐ Yes - ES5+ compatible, cleaner diffs B) No Formatter & Linter: A) ⭐ Prettier + ESLint - Recommended combination - Prettier: Auto-format on save (style/formatting) - ESLint: Code quality and error detection - Use eslint-config-prettier to avoid conflicts B) ESLint only - With formatting rules - Handles both linting and formatting - More config overhead C) Prettier only - Formatting without linting - Fast, opinionated formatting - No code quality checks D) EditorConfig only - Basic cross-editor consistency E) Manual formatting - Not recommended Your choice: __ ``` **5.2 Naming Conventions** ``` Naming style by type: Files: A) ⭐ kebab-case - user-service.ts, api-controller.ts B) camelCase - userService.ts, apiController.ts C) PascalCase - UserService.ts, ApiController.ts Classes/Interfaces: A) ✅ PascalCase - UserService, IUserRepository Functions/Methods: A) ✅ camelCase - getUserById, createOrder Variables: A) ✅ camelCase - userName, totalPrice Constants: A) ✅ UPPER_SNAKE_CASE - MAX_RETRIES, API_BASE_URL Interfaces (TypeScript): A) ⭐ I-prefix - IUserService, IRepository B) No prefix - UserService, Repository C) -Interface suffix - UserServiceInterface Boolean variables: A) ✅ is/has/can prefix - isActive, hasPermission, canEdit ``` **5.3 File Organization** > **Note:** The AI will adapt the following examples to match your selected language/framework from Phase 3 (questions 3.1 and 3.2). File extensions, naming conventions, and folder names will be automatically adjusted. ``` Project structure approach: A) ⭐ Feature-based (Modular) - Recommended for most projects Group by feature/module with subfolders for organization: [DYNAMIC EXAMPLE - AI will adapt based on your stack] TypeScript/NestJS example: src/ modules/ users/ dto/ create-user.dto.ts update-user.dto.ts entities/ user.entity.ts users.controller.ts users.service.ts users.repository.ts users.module.ts orders/ dto/ entities/ orders.controller.ts common/ guards/ interceptors/ config/ Python/FastAPI example: src/ modules/ users/ schemas/ user_create.py user_update.py models/ user.py users_controller.py users_service.py users_repository.py orders/ schemas/ models/ common/ dependencies/ middleware/ Java/Spring Boot example: src/main/java/com/myapp/ modules/ users/ dto/ CreateUserDto.java UpdateUserDto.java domain/ User.java UsersController.java UsersService.java UsersRepository.java orders/ common/ config/ security/ Go example: src/ modules/ users/ models/ user.go handlers/ user_handler.go services/ user_service.go repositories/ user_repository.go orders/ common/ middleware/ C#/.NET Core example: src/ Modules/ Users/ DTOs/ CreateUserDto.cs UpdateUserDto.cs Entities/ User.cs UsersController.cs UsersService.cs UsersRepository.cs Orders/ DTOs/ Entities/ Common/ Middleware/ Extensions/ Benefits: Scalable, easy to find related code, clear module boundaries --- B) 🏆 Feature-based (Flat) - Simple projects Flat structure within each feature (AI will adapt naming): src/ users/ user_controller user_service user_repository user_dto user_entity orders/ order_controller order_service ... Benefits: Simpler, fewer folders, good for small projects --- C) Layer-based (Traditional) - Legacy style Group by technical layer/type (AI will adapt naming): src/ controllers/ user_controller order_controller services/ user_service order_service repositories/ user_repository order_repository entities/ user_entity order_entity dto/ create_user_dto create_order_dto Benefits: Clear separation by type, familiar for MVC developers Drawbacks: Hard to see feature boundaries, files scattered --- D) Hybrid - Domain + Shared layers Modules for features + shared technical folders (AI will adapt): src/ modules/ users/ (feature code) orders/ (feature code) shared/ services/ utils/ infrastructure/ database/ .ai-flow/cache/ Your choice: __ Why? --- After you select, the AI will generate the exact folder structure with proper: - File extensions (.ts, .py, .java, .go) - Naming conventions (camelCase, snake_case, PascalCase) - Framework-specific folders (dto vs schemas, entities vs models vs domain) - Common patterns for your chosen stack ``` **5.4 Import Organization** ``` Import ordering: A) ⭐ Recommended order: 1. External libraries (react, express, etc.) 2. Internal modules (@/services, @/utils) 3. Relative imports (./user.dto, ../shared) 4. Types/Interfaces 5. Styles/Assets B) Alphabetical C) No specific order Path aliases: A) ✅ Yes - Use @ for src root - import { UserService } from '@/services/user.service'; B) No - Use relative paths only ``` **5.5 TypeScript/Type Rules** ``` (Skip if not using TypeScript) A) ✅ Strict mode - Enable all strict checks ⭐ B) ❌ any allowed - Use any when needed (not recommended) C) ⚠️ Gradual typing - Start loose, tighten over time Rules: - ✅ No implicit any - ✅ Strict null checks - ✅ No unused variables - ✅ Explicit function return types - ✅ Interface over type (when possible) Type preference: A) Interfaces for object shapes B) Types for unions/intersections C) Mix both as needed ⭐ ``` **5.6 Error Handling** ``` Error handling strategy: A) ⭐ Try-catch with custom error classes - Centralized error handler - HTTP error mapping - Detailed error messages B) Error codes/enums - Consistent error codes across app C) Result pattern - Never throw, return Result Your approach: __ Error logging: A) ⭐ All errors logged with context B) Only server errors (5xx) C) Errors + warnings Error responses to client: A) ⭐ Detailed in dev, generic in production - Dev: Full stack trace - Prod: Error code + user-friendly message B) Always detailed C) Always generic ``` **5.7 Comments & Documentation** ```` When to comment: A) ⭐ Recommended approach: - Complex business logic - Non-obvious solutions - TODOs and FIXMEs - Public APIs (JSDoc/Docstrings) - Configuration decisions B) Minimal comments - Self-documenting code only C) Extensive comments - Every function Doc comments: A) ✅ JSDoc for TypeScript/JavaScript B) ✅ Docstrings for Python C) ✅ JavaDoc for Java Example: ```typescript /** * Calculates user's total order value for the current month * @param userId - The unique user identifier * @param includeDiscounts - Whether to apply promotional discounts * @returns Total value in cents */ async function calculateMonthlyTotal( userId: string, includeDiscounts: boolean ): Promise; ``` ```` **5.8 Testing Standards** ``` Test coverage requirements: Minimum coverage: A) 🏆 80%+ - Enterprise standard B) ⭐ 70%+ - Recommended for most projects C) 50%+ - Minimum acceptable D) No requirement What to test: - ✅ Services/Business logic - 80%+ coverage - ✅ Controllers/Routes - 60%+ coverage - ✅ Utilities/Helpers - 90%+ coverage - ✅ Database repositories - 70%+ coverage - ❓ DTOs/Entities - Usually no tests needed Test file naming: A) ⭐ .spec.ts / .test.ts - Next to source file B) Separate tests/ folder Mocking strategy: A) ⭐ Mock external dependencies (DB, APIs) B) Integration tests with real DB C) Mix: Unit tests mock, integration tests don't ``` **5.9 Code Complexity Limits** ``` Code quality metrics: Function length: A) ⭐ Max 50 lines per function B) Max 100 lines C) No limit Cyclomatic complexity: A) ⭐ Max complexity 10 B) Max complexity 15 C) No limit Parameters: A) ⭐ Max 4 parameters (use object for more) B) Max 6 parameters C) No limit Nesting depth: A) ⭐ Max 3 levels B) Max 4 levels C) No limit ``` **5.10 Git Commit Standards** ```` Commit message format: A) ⭐ Conventional Commits ``` ():