typescript-code-standards

TypeScript Code Style and Standards

Context

• When writing TypeScript code for Angular or Vue applications
• When reviewing TypeScript code
• When modifying existing TypeScript code
• When implementing new features
• When refactoring existing code
• When working with modern SPA frameworks

Requirements

File Documentation

Public API files and complex modules should be documented using the following format:

/**
 * Brief one-line description of the file/module.
 * 
 * More detailed description of the module functionality,
 * including its purpose, key features, and usage examples.
 * 
 */

Function Documentation

All exported public functions and non-obvious internal functions should be documented:

/**
 * Brief description of what the function does.
 * 
 * More detailed description if necessary, including any
 * important implementation details or usage notes.
 * 
 * @param paramName - Description of the parameter
 * @returns Description of the return value
 * @throws ErrorType Description of when/why this error is thrown
 * @example
 * ```typescript
 * const result = functionName('param');
 * ```
 */

Interface Documentation

Document all public interfaces and complex internal interfaces:

/**
 * Brief description of the interface.
 * 
 * More detailed description of the interface purpose
 * and usage patterns.
 */
interface InterfaceName {
  /** Description of the property */
  propertyName: string;
  
  /** Description of the method */
  methodName(): void;
}

Code Organization

1. File Structure (in order):

   • File documentation
   • Imports (organized and grouped)
   • Type definitions
   • Interfaces
   • Classes
   • Functions
   • Constants
   • Exports

2. Import Organization:

   • Node.js built-in modules
   • Third-party libraries
   • Project-specific imports
   • No wildcard imports (*)

Naming Conventions

1. Interfaces:
   • PascalCase
   • Nouns or noun phrases
   • Clear and descriptive