Skip to main content

Code Standards

General Principles​

1. Clean Code​

  • Write self-documenting code
  • Keep functions small and focused
  • Use meaningful names
  • Maintain consistent formatting
  • Follow DRY principle

2. SOLID Principles​

  • Single Responsibility
  • Open/Closed
  • Liskov Substitution
  • Interface Segregation
  • Dependency Inversion

3. Code Organization​

  • Logical file structure
  • Component-based architecture
  • Clear module boundaries
  • Consistent naming patterns
  • Proper encapsulation

Language-Specific Standards​

JavaScript/TypeScript​

// Variables: camelCase
const userName = 'John';
let itemCount = 0;

// Constants: UPPER_CASE
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = '/api/v1';

// Classes: PascalCase
class UserService {
  private users: User[];
  
  constructor() {
    this.users = [];
  }
  
  // Methods: camelCase
  public async getUser(id: string): Promise<User> {
    // Implementation
  }
}

// Interfaces: PascalCase with 'I' prefix
interface IUser {
  id: string;
  name: string;
  email: string;
}

// Type aliases: PascalCase
type UserRole = 'admin' | 'user' | 'guest';

Python​

# Module names: lowercase with underscores
import user_service

# Classes: PascalCase
class UserService:
    def __init__(self):
        self._users = []
    
    # Methods: lowercase with underscores
    def get_user(self, user_id: str) -> User:
        # Implementation
        pass

# Variables: lowercase with underscores
user_name = "John"
item_count = 0

# Constants: UPPER_CASE
MAX_RETRY_COUNT = 3
API_BASE_URL = "/api/v1"

Documentation Standards​

1. Code Comments​

/**
 * Retrieves user information from the database
 * @param {string} id - The user's unique identifier
 * @returns {Promise<User>} The user object
 * @throws {NotFoundError} When user is not found
 */
async function getUser(id: string): Promise<User> {
  // Implementation
}

2. README Files​

# Component Name

Brief description of the component's purpose

## Usage
Example usage code

## Props
| Name | Type | Required | Description |
|------|------|----------|-------------|
| prop1 | string | Yes | Description |
| prop2 | number | No | Description |

## Methods
Available public methods

## Events
Available events

3. API Documentation​

/**
 * @api {post} /api/users Create User
 * @apiName CreateUser
 * @apiGroup Users
 *
 * @apiParam {String} name User's full name
 * @apiParam {String} email User's email address
 *
 * @apiSuccess {String} id User's unique ID
 * @apiSuccess {Object} user Created user object
 *
 * @apiError {Object} error Error object with message
 */

Testing Standards​

1. Unit Tests​

describe('UserService', () => {
  let service: UserService;
  
  beforeEach(() => {
    service = new UserService();
  });
  
  it('should create user successfully', async () => {
    // Arrange
    const userData = { name: 'John', email: '[email protected]' };
    
    // Act
    const result = await service.createUser(userData);
    
    // Assert
    expect(result).toBeDefined();
    expect(result.name).toBe(userData.name);
  });
});

2. Integration Tests​

describe('User API', () => {
  it('should create and retrieve user', async () => {
    // Create user
    const createResponse = await request(app)
      .post('/api/users')
      .send(userData);
    
    // Verify creation
    expect(createResponse.status).toBe(201);
    
    // Retrieve user
    const getResponse = await request(app)
      .get(`/api/users/${createResponse.body.id}`);
    
    // Verify retrieval
    expect(getResponse.status).toBe(200);
    expect(getResponse.body).toMatchObject(userData);
  });
});

Error Handling​

1. Custom Errors​

class ApplicationError extends Error {
  constructor(message: string, public code: string) {
    super(message);
    this.name = 'ApplicationError';
  }
}

class NotFoundError extends ApplicationError {
  constructor(resource: string) {
    super(`${resource} not found`, 'NOT_FOUND');
    this.name = 'NotFoundError';
  }
}

2. Error Responses​

interface ErrorResponse {
  error: {
    code: string;
    message: string;
    details?: any;
  }
}

function handleError(error: Error): ErrorResponse {
  return {
    error: {
      code: error instanceof ApplicationError ? error.code : 'INTERNAL_ERROR',
      message: error.message,
    }
  };
}

Performance Considerations​

1. Code Optimization​

  • Use appropriate data structures
  • Implement caching where needed
  • Optimize database queries
  • Minimize HTTP requests
  • Use lazy loading

2. Resource Management​

  • Clean up resources properly
  • Implement connection pooling
  • Handle memory efficiently
  • Use streaming for large data
  • Implement rate limiting