Style Guide

Overview

QODRYX can enforce your team's coding standards automatically. Instead of manual review cycles discussing code style, the AI reviewer can catch style violations and suggest fixes based on your custom guidelines.

Built-in Style Checks

Out of the box, QODRYX checks for common style issues:

Custom Style Guide

Define your team's coding standards in a markdown file that QODRYX will reference:

Creating a Style Guide

Create a STYLE_GUIDE.md in your repository:

# Company Style Guide

## Naming Conventions

### Variables
- Use camelCase for variables and functions
- Use PascalCase for classes and components
- Use SCREAMING_SNAKE_CASE for constants
- Prefix boolean variables with is, has, should, can

### Files
- Use kebab-case for file names
- React components: ComponentName.tsx
- Utilities: utility-name.ts
- Tests: file-name.test.ts

## Code Organization

### Imports
Order imports as follows:
1. External packages (react, lodash, etc.)
2. Internal aliases (@/components, @/utils)
3. Relative imports (./local-file)
4. Type imports (import type { ... })

### Function Length
- Functions should be under 30 lines
- If longer, consider extracting helper functions

## Documentation

### Functions
All exported functions must have JSDoc:
```typescript
/**
 * Brief description of what the function does.
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws Description of possible errors
 */
```

### Components
React components must have prop documentation:
```typescript
interface ButtonProps {
  /** The button label text */
  label: string;
  /** Called when button is clicked */
  onClick: () => void;
  /** Visual variant of the button */
  variant?: 'primary' | 'secondary';
}
```

## Error Handling

- Always use try-catch for async operations
- Never swallow errors silently
- Log errors with context:
  ```typescript
  catch (error) {
    logger.error('Failed to fetch user', { userId, error });
    throw new UserFetchError('Unable to load user data');
  }
  ```

## Testing

- Each new feature must include tests
- Test files must be co-located with source files
- Use descriptive test names: "should X when Y"
- Mock external dependencies, not internal modules

Referencing the Style Guide

Tell QODRYX where to find your style guide:

# qodryx.yml
code_review:
  style_guide: "./STYLE_GUIDE.md"
  
  # Or reference multiple guides
  style_guides:
    - "./STYLE_GUIDE.md"
    - "./docs/TYPESCRIPT_GUIDE.md"
    - "./docs/REACT_PATTERNS.md"

Custom Rules

Define specific patterns to enforce or prevent:

# qodryx.yml
code_review:
  rules:
    # Prevent console.log in production code
    - name: no-console-log
      pattern: "console\.(log|debug|info)"
      exclude: ["*.test.ts", "*.spec.ts"]
      message: "Remove console statements before merging"
      severity: warning
      fix:
        suggest: "Use the logger utility instead: import { logger } from '@/utils/logger'"
    
    # Require error handling for fetch calls
    - name: fetch-error-handling
      pattern: "await\s+fetch\("
      require: "(try\s*\{|\}\.catch\()"
      message: "API calls must have error handling"
      severity: high
    
    # Enforce consistent async/await usage
    - name: prefer-async-await
      pattern: "\.then\(.*\.then\("
      message: "Use async/await instead of chained .then()"
      severity: info
      
    # Require tests for new components
    - name: require-component-tests
      trigger: 
        file_pattern: "src/components/**/*.tsx"
        condition: "new_file"
      require:
        file_exists: "{filename}.test.tsx"
      message: "New components must have a test file"
      severity: high
    
    # Prevent direct DOM manipulation in React
    - name: no-direct-dom
      pattern: "document\.(getElementById|querySelector|getElementsBy)"
      message: "Use React refs instead of direct DOM manipulation"
      severity: warning
      
    # Enforce import ordering
    - name: import-order
      pattern: "^import"
      order:
        - "^react"
        - "^@?\w"
        - "^@/"
        - "^\.\."
        - "^\."
      message: "Imports should follow the standard ordering"
      severity: info

Language-Specific Rules

TypeScript/JavaScript

rules:
  # Require explicit return types
  - name: explicit-return-types
    pattern: "export (async )?function \w+\([^)]*\)(?!:)"
    message: "Exported functions should have explicit return types"
    severity: warning
  
  # Prefer const over let
  - name: prefer-const
    pattern: "let\s+\w+\s*=(?!.*\n.*\1\s*=)"
    message: "Use const for variables that are never reassigned"
    severity: info
    
  # No any type
  - name: no-any
    pattern: ":\s*any\b"
    message: "Avoid using 'any' type. Use 'unknown' or a specific type"
    severity: warning

Python

rules:
  # Require type hints
  - name: type-hints
    pattern: "def\s+\w+\([^)]*\)(?!\s*->)"
    exclude: ["tests/**"]
    message: "Functions should have return type hints"
    severity: warning
  
  # Docstring required
  - name: require-docstring
    pattern: "def\s+[a-z_]+\([^)]*\):\n(?!\s+""")"
    message: "Public functions should have docstrings"
    severity: info

React

rules:
  # Use function components
  - name: prefer-function-components
    pattern: "class\s+\w+\s+extends\s+(React\.)?Component"
    message: "Prefer function components over class components"
    severity: info
  
  # Destructure props
  - name: destructure-props
    pattern: "props\."
    message: "Consider destructuring props for cleaner code"
    severity: info
    
  # Key prop in lists
  - name: require-key-prop
    pattern: "\.map\([^)]*\)\s*=>\s*<(?![^>]*key=)"
    message: "Add a unique 'key' prop to list items"
    severity: high

Severity Levels

Auto-Fix Suggestions

Provide automatic fix suggestions for your rules:

- name: use-optional-chaining
  pattern: "(\w+)\s+&&\s+\1\.(\w+)"
  message: "Use optional chaining instead"
  severity: info
  fix:
    replace: "$1?.$2"
    example:
      before: "user && user.name"
      after: "user?.name"

Ignoring Rules

Sometimes you need to bypass style rules for specific cases:

Inline Comments

// qodryx-disable-next-line no-console-log
console.log('Intentional debug output');

/* qodryx-disable no-any */
const legacyData: any = fetchLegacyAPI();
/* qodryx-enable no-any */

File-Level Ignores

# qodryx.yml
code_review:
  rules:
    - name: require-component-tests
      # ...
      exclude:
        - "src/components/legacy/**"
        - "src/components/generated/**"

Best Practices

Next Steps