Debe preferir usar el gestor de versiones "pnpm" por sobre "npm" para la ejecución de los comandos.
i201623372
Created May 20, 2025
# TypeScript Performance Optimization Standards: Best Practices for Efficient Applications This document outlines coding standards and best practices specifically for performance optimization in TypeScript projects. Adhering to these guidelines will improve the speed, responsiveness, efficient use of resources, and overall user experience of your applications. ## Table of Contents - [1. Architectural Considerations for Performance](#1-architectural-considerations-for-performance) - [1.1. Code Splitting](#11-code-splitting) - [1.2. Lazy Loading Modules](#12-lazy-loading-modules) - [1.3. Server-Side Rendering (SSR) or Static Site Generation (SSG)](#13-server-side-rendering-ssr-or-static-site-generation-ssg) - [1.4. Data Structure Selection](#14-data-structure-selection) ## 1. Architectural Considerations for Performance ### 1.1. Code Splitting **Standard:** Implement code splitting to reduce the initial load time of your application. **Why:** Loading only the necessary code on initial page load significantly improves the user experience. **Do This:** * Utilize dynamic imports (`import()`) to load modules on demand. * Configure your bundler (Webpack, Parcel, Rollup) to create separate chunks for different parts of your application. **Don't Do This:** * Load the entire application code in a single bundle. * Use `require()` statements (CommonJS) in modern TypeScript projects where ES Modules are supported. **Example:** ```typescript // Before: Loading everything upfront import { featureA } from './featureA'; import { featureB } from './featureB'; // After: Code splitting with dynamic imports async function loadFeatureA() { const { featureA } = await import('./featureA'); featureA.init(); } async function loadFeatureB() { const { featureB } = await import('./featureB'); featureB.init(); } // Use loadFeatureA or loadFeatureB based on user interaction or route ``` **Bundler Configuration (Webpack example):** ```javascript // webpack.config.js module.exports = { entry: './src/index.ts', output: { filename: '[name].bundle.js', path: path.resolve(__dirname, 'dist'), }, module: { rules: [ { test: /\.tsx?$/, use: 'ts-loader', exclude: /node_modules/, }, ], }, resolve: { extensions: ['.tsx', '.ts', '.js'], }, optimization: { splitChunks: { chunks: 'all', // Split all chunks of code }, }, }; ``` ### 1.2. Lazy Loading Modules **Standard:** Employ lazy loading for non-critical modules or components. **Why:** Reduce the amount of code that needs to be parsed and compiled on initial load. **Do This:** * Load components or modules only when they are needed. * Utilize Intersection Observer API to load components when they become visible in the viewport. **Don't Do This:** * Load modules that are not immediately required for the current user interaction. **Example (Intersection Observer Lazy Loading):** ```typescript function lazyLoadComponent(element: HTMLElement, importPath: string) { const observer = new IntersectionObserver((entries) => { entries.forEach(async (entry) => { if (entry.isIntersecting) { const { default: Component } = await import(importPath); const componentInstance = new Component(); // Instantiate the component. element.appendChild(componentInstance.render()); // Append to the DOM (adjust according to your framework). observer.unobserve(element); } }); }); observer.observe(element); } // Usage: const lazyComponentElement = document.getElementById('lazy-component'); if (lazyComponentElement) { lazyLoadComponent(lazyComponentElement, './MyHeavyComponent'); } ``` ### 1.3. Server-Side Rendering (SSR) or Static Site Generation (SSG) **Standard:** Consider using SSR or SSG for content-heavy, SEO-sensitive, or performance-critical applications. **Why:** Reduces the time to first paint (TTFP) and improves SEO by providing crawlers with pre-rendered content. **Do This:** * Evaluate the trade-offs between SSR, SSG, and client-side rendering (CSR) based on your application's needs. * Use frameworks like Next.js (React), Nuxt.js (Vue), or Angular Universal. * Implement appropriate caching strategies for SSR. **Don't Do This:** * Default to CSR when SSR or SSG could provide significant performance benefits. **Example (Next.js):** ```typescript // pages/index.tsx (Next.js example) import React from 'react'; interface Props { data: { title: string; description: string; }; } const HomePage: React.FC<Props> = ({ data }) => { return ( <div> <h1>{data.title}</h1> <p>{data.description}</p> </div> ); }; export async function getServerSideProps() { // Fetch data from an API, database, or file system. const data = { title: 'My Awesome Website', description: 'Welcome to my extremely performant website!', }; return { props: { data, }, }; } export default HomePage; ``` ### 1.4. Data Structure Selection **Standard:** Select the most appropriate data structure for each specific use case. **Why:** Using appropriate data structures will reduce the complexity and improve the execution speed of algorithms. **Do This:** * Use `Map` when you need to associate keys with values, especially when the keys are not strings or numbers. * Use `Set` when you need to store a collection of unique values. * Use `Record<K, V>` type for type-safe object mapping. * Consider specialized data structures for specific performance needs (e.g., priority queues, linked lists). **Don't Do This:** * Use generic arrays or objects when more specialized data structures would be more efficient. * Perform frequent lookups in arrays when using a Map or Set would be more performant. **Example:** ```typescript // Before: Using an array for lookups const users = [ { id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, { id: 3, name: 'Charlie' } ]; // O(n) lookup operation const findUser = (id: number) => users.find(user => user.id === id); // After: Using Map for efficient lookups const userMap = new Map<number, {id: number, name: string}>(); userMap.set(1, { id: 1, name: 'Alice' }); userMap.set(2, { id: 2, name: 'Bob' }); userMap.set(3, { id: 3, name: 'Charlie' }); // O(1) lookup operation const getUser = (id: number) => userMap.get(id); ```
# Core Architecture Standards for JavaScript This document outlines the core architecture standards for JavaScript development. It's intended to guide developers and serve as context for AI coding assistants. The focus is on creating maintainable, performant, and secure JavaScript code. We will emphasize modern JavaScript practices and patterns. ## 1. Fundamental Architectural Patterns ### 1.1. Modular Architecture **Standard:** Structure applications into independent, reusable modules. **Why:** Improves code organization, testability, and reusability. Modules encapsulate functionality, reduce dependencies, prevent naming conflicts, and allow for easier maintenance and updates. **Do This:** Employ ES Modules (ESM) for native modularity. """javascript // myModule.js export function myFunction(param) { return param * 2; } export const myConstant = "Hello"; // main.js import { myFunction, myConstant } from './myModule.js'; console.log(myFunction(5)); // Output: 10 console.log(myConstant); // Output: Hello """ **Don't Do This:** Use global variables or pollute the global namespace. Avoid relying on script loading order. """javascript // Anti-pattern - global scope pollution function badFunction() { window.globalVariable = "Avoid this"; // Avoid } """ ### 1.2. Component-Based Architecture **Standard:** Design UIs as a composition of reusable components. **Why:** Promote code reuse, simplify testing, and improve UI maintainability. Components represent isolated parts of the application's UI. **Do This:** Utilize frameworks like React, Vue, or Angular. If building from scratch, establish clear component boundaries. Here's an example using React: """jsx // MyComponent.jsx import React from 'react'; function MyComponent({ name }) { return ( <div> <h1>Hello, {name}!</h1> </div> ); } export default MyComponent; // App.jsx import React from 'react'; import MyComponent from './MyComponent'; function App() { return ( <div> <MyComponent name="World" /> </div> ); } export default App; """ **Don't Do This:** Create monolithic, tightly coupled UI code. Avoid duplicating UI elements and logic. ### 1.3. Microservices (for backends) **Standard:** Decompose large applications into smaller, independently deployable microservices. **Why:** Allows for independent scaling, fault isolation, and technology diversity. Each microservice addresses a specific business capability. **Do This:** Design clear API boundaries (REST or GraphQL). Implement robust inter-service communication (e.g., asynchronous messaging via Kafka/RabbitMQ). Use containerization (Docker) and orchestration (Kubernetes). """javascript // Example (Conceptual) - Microservice A (User Service) // Implements API endpoints for user management // Example (Conceptual) - Microservice B (Order Service) // Implements API endpoints for order processing. Communicates with User Service to validate users. """ **Don't Do This:** Create tightly coupled services, share databases between services (unless absolutely necessary and carefully managed), or implement complex, monolithic APIs. ### 1.4. Event-Driven Architecture **Standard:** Design systems to react to events, enabling loose coupling and asynchronous communication. **Why:** Improves scalability, responsiveness, and resilience. Components interact by emitting and listening to events. **Do This:** Use message queues (RabbitMQ, Kafka), publish-subscribe patterns, or libraries like Node.js's "EventEmitter". Implement webhooks or server-sent events (SSE). """javascript // Example using Node.js EventEmitter const EventEmitter = require('events'); class MyEmitter extends EventEmitter {} const myEmitter = new MyEmitter(); myEmitter.on('event', (data) => { console.log('Event occurred:', data); }); myEmitter.emit('event', { message: 'Hello from event emitter!' }); """ **Don't Do This:** Create tightly coupled event chains, ignore event handling errors, or rely solely on synchronous event processing for critical tasks. Avoid excessively broad event scopes. ## 2. Project Structure and Organization ### 2.1. Directory Structure **Standard:** Follow a consistent and well-defined project structure. **Why:** Improves project navigation, maintainability, and developer onboarding. **Do This:** Adopt a structure like: """ project-root/ ├── src/ # Source code │ ├── components/ # Reusable UI components │ │ ├── MyComponent/ │ │ │ ├── MyComponent.jsx │ │ │ ├── MyComponent.module.css # CSS Modules (Optional) │ │ │ └── index.js # Entry point (Optional) │ ├── pages/ # Application routes/pages │ │ ├── HomePage.jsx │ │ ├── AboutPage.jsx │ ├── services/ # API client logic │ │ ├── userService.js │ ├── utils/ # Utility functions │ │ ├── dateUtils.js │ ├── App.jsx # Main application component │ ├── index.js # Entry point for the application ├── public/ # Static assets (images, fonts) ├── config/ # Configuration files ├── scripts/ # Build and utility scripts ├── tests/ # Unit and integration tests ├── .eslintrc.js # ESLint configuration ├── package.json # Project dependencies and metadata └── README.md # Project documentation """ **Don't Do This:** Scatter files randomly, use inconsistent naming conventions, or create a deeply nested structure that's hard to navigate. ### 2.2. Naming Conventions **Standard:** Adhere to clear and consistent naming conventions. **Why:** Improves code readability and maintainability. **Do This:** * **Variables/Constants:** Use camelCase (e.g., "myVariable", "myConstant"). Use SCREAMING_SNAKE_CASE for truly immutable constants (e.g., "MAX_SIZE"). * **Functions:** Use camelCase (e.g., "getUserData", "calculateTotal"). * **Classes:** Use PascalCase (e.g., "MyClass", "UserData"). * **Components:** Use PascalCase (e.g., "MyComponent", "UserProfile"). Match filename to component name. * **Files:** Use kebab-case (e.g., "user-service.js", "my-component.jsx"). Match filename to exported function or component name. * **Directories:** Use kebab-case or PascalCase (for component directories). * **Booleans:** Start with "is", "has", or "should" (e.g., "isEnabled", "hasPermission", "shouldUpdate"). **Don't Do This:** Use ambiguous or cryptic names, use inconsistent casing, or use reserved keywords. ### 2.3. Code Style and Formatting **Standard:** Enforce a consistent code style across the project. **Why:** Improves code readability and collaboration. **Do This:** * Use "ESLint" with a predefined style guide (e.g., Airbnb, Google, Standard). * Use "Prettier" for automated code formatting. * Configure your IDE/editor to automatically format code on save. * Use single quotes for strings unless double quotes are needed for escaping. * Use 2 spaces for indentation. * Add a final newline to all files. """javascript // Example using ESLint and Prettier // .eslintrc.js module.exports = { "extends": "eslint:recommended", "parserOptions": { "ecmaVersion": 2020, "sourceType": "module" }, "env": { "browser": true, "node": true, "es6": true }, "rules": { "semi": ["error", "always"], "quotes": ["error", "single"], "no-unused-vars": "warn", "no-console": "warn" } }; // .prettierrc.js module.exports = { semi: true, trailingComma: 'all', singleQuote: true, printWidth: 120, tabWidth: 2, }; """ **Don't Do This:** Ignore code style guidelines, commit code with formatting errors, or use inconsistent indentation. ## 3. Modern JavaScript Features and Practices ### 3.1. Asynchronous Programming (async/await) **Standard:** Use "async/await" for cleaner asynchronous code. **Why:** Improves code readability and maintainability compared to callbacks or promises. **Do This:** """javascript async function fetchData() { try { const response = await fetch('https://api.example.com/data'); const data = await response.json(); return data; } catch (error) { console.error('Error fetching data:', error); throw error; // Re-throw to propagate the error } } fetchData() .then(data => console.log('Data:', data)) .catch(error => console.error('Caught error:', error)); // Added top-level catch in calling function """ **Don't Do This:** Mix callbacks and promises with "async/await", forget to handle errors with "try/catch", or use "async/await" unnecessarily in synchronous code. Also, place try/catch blocks within your async functions. Remember to handle rejected promises in the function that calls the async function in the event that the async function throws an error. ### 3.2. ES Modules **Standard:** Use ES Modules (ESM) for modularizing code. **Why:** Standardized module system with native browser support and better tooling. **Do This:** """javascript // myModule.js export function add(a, b) { return a + b; } // main.js import { add } from './myModule.js'; console.log(add(2, 3)); // Output: 5 """ **Don't Do This:** Use CommonJS modules ("require", "module.exports") in new projects unless specifically required by the environment (Node.js might still require for certain configuration files but try to avoid). Mix ESM and CommonJS without proper tooling. ### 3.3. Destructuring and Spread Syntax **Standard:** Use destructuring and spread syntax for concise and readable code manipulation. **Why:** Reduce boilerplate code and improve code clarity. **Do This:** """javascript // Destructuring const user = { name: 'John', age: 30, city: 'New York' }; const { name, age } = user; console.log(name, age); // Output: John 30 // Spread syntax const arr1 = [1, 2, 3]; const arr2 = [...arr1, 4, 5]; console.log(arr2); // Output: [1, 2, 3, 4, 5] const user2 = { ...user, occupation: 'Developer' }; console.log(user2); """ **Don't Do This:** Overuse destructuring to the point of reducing readability, or modify props directly when using the spread operator in React (create a new object instead). ### 3.4. Functional Programming Concepts **Standard:** Embrace functional programming concepts like immutability, pure functions, and higher-order functions. **Why:** Improve code testability, predictability, and reduce side effects. **Do This:** """javascript // Pure function function add(a, b) { return a + b; // No side effects } // Immutability const numbers = [1, 2, 3]; const newNumbers = numbers.map(num => num * 2); // Create a new array console.log(numbers); // Output: [1, 2, 3] console.log(newNumbers); // Output: [2, 4, 6] """ **Don't Do This:** Mutate data directly, rely on side effects, or create functions with hidden dependencies. ## 4. Security Best Practices ### 4.1. Input Validation **Standard:** Validate all user inputs on both client and server sides. **Why:** Prevent injection attacks (XSS, SQL injection), data corruption, and unexpected behavior. **Do This:** * Use a validation library (e.g., Joi, validator.js). * Sanitize inputs to remove potentially harmful characters. * Implement proper error handling for invalid inputs. """javascript // Example using Joi for input validation const Joi = require('joi'); const schema = Joi.object({ username: Joi.string().alphanum().min(3).max(30).required(), password: Joi.string().pattern(new RegExp('^[a-zA-Z0-9]{3,30}$')).required(), email: Joi.string().email({ tlds: { allow: ['com', 'net'] } }).required(), }); const userInput = { username: 'john_doe', password: 'securePassword', email: 'john.doe@example.com', }; const validationResult = schema.validate(userInput); if (validationResult.error) { console.error('Validation error:', validationResult.error.details); } else { console.log('Input is valid'); } """ **Don't Do This:** Trust user inputs implicitly, rely solely on client-side validation, or expose sensitive information in error messages. ### 4.2. Authentication and Authorization **Standard:** Implement secure authentication and authorization mechanisms. **Why:** Protect sensitive data and prevent unauthorized access. **Do This:** * Use a reputable authentication library (e.g., Passport.js, Auth0). * Store passwords securely using hashing algorithms (e.g., bcrypt). * Implement role-based access control (RBAC). * Use JSON Web Tokens (JWT) for stateless authentication. * Implement multi-factor authentication (MFA). """javascript // Example (Conceptual) - Authentication using JWT // Generating a JWT const jwt = require('jsonwebtoken'); const payload = { userId: 123, role: 'admin' }; const secretKey = 'mySecretKey'; // Store securely! const token = jwt.sign(payload, secretKey, { expiresIn: '1h' }); console.log('Generated token:', token); // Verifying a JWT jwt.verify(token, secretKey, (err, decoded) => { if (err) { console.error('Token verification failed:', err); } else { console.log('Decoded token:', decoded); } }); """ **Don't Do This:** Store passwords in plain text, use weak hashing algorithms, or implement custom authentication schemes without proper security expertise. ### 4.3. Cross-Site Scripting (XSS) Prevention **Standard:** Prevent cross-site scripting (XSS) attacks by properly escaping and sanitizing output. **Why:** Prevent malicious scripts from being injected into your application. **Do This:** * Escape HTML entities when rendering user-generated content. Libraries like DOMPurify are helpful. * Use Content Security Policy (CSP) headers to restrict the sources of scripts and other resources. """html <!-- Example CSP header --> <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' https://trusted-cdn.com; style-src 'self' https://trusted-cdn.com; img-src 'self' data:"> """ **Don't Do This:** Render unescaped user input directly into the DOM, or allow inline JavaScript. ### 4.4. Cross-Site Request Forgery (CSRF) Prevention **Standard:** Prevent cross-site request forgery (CSRF) attacks by using anti-CSRF tokens. **Why:** Prevent malicious websites from making unauthorized requests on behalf of authenticated users. **Do This:** * Include a unique, unpredictable token in each form. * Verify the token on the server side before processing the request. * Use the "SameSite" attribute on cookies to prevent them from being sent with cross-origin requests. ## 5. Performance Optimization ### 5.1. Code Splitting **Standard:** Split your code into smaller chunks that can be loaded on demand. **Why:** Reduce initial load time and improve overall performance. **Do This:** * Use dynamic imports ("import()"). * Configure your bundler (Webpack, Parcel, Rollup) for code splitting. * Split code based on routes, components, or features. """javascript // Example using dynamic import async function loadComponent() { const { MyComponent } = await import('./MyComponent.js'); // Render MyComponent } """ **Don't Do This:** Load all code upfront, or create excessively small chunks that increase the number of HTTP requests. ### 5.2. Lazy Loading **Standard:** Load resources (images, components) only when they are needed. **Why:** Improve initial load time and reduce memory consumption. **Do This:** * Use "IntersectionObserver" to detect when an element is in the viewport. * Implement lazy loading for images using the "loading="lazy"" attribute (where supported) or JavaScript libraries. """html <img src="image.jpg" loading="lazy" alt="Lazy-loaded image"> """ """javascript //Example using Intersection Observer const lazyImages = document.querySelectorAll('.lazy-image'); const observer = new IntersectionObserver((entries) => { entries.forEach(entry => { if(entry.isIntersecting){ let lazyImage = entry.target; lazyImage.src = lazyImage.dataset.src; lazyImage.classList.remove('lazy-image'); observer.unobserve(lazyImage); } }); }); lazyImages.forEach(lazyImage => { observer.observe(lazyImage); }); """ **Don't Do This:** Load all resources upfront, or implement complex lazy loading logic for small resources. ### 5.3. Memoization **Standard:** Cache the results of expensive function calls. **Why:** Avoid redundant computations and improve performance. **Do This:** * Implement memoization using a simple cache object or a library like "memoize-one". * Use "React.memo" for memoizing React components. """javascript //Basic memoization technique function memoize(func){ const cache = {}; return function(...args){ const key = JSON.stringify(args); //Create a key from the arguments if(cache[key]){ return cache[key]; } const result = func(...args); cache[key] = result; return result; } } const expensiveFunction = (arg) => { console.log('computing...') return arg * 2; } const memoizedExpensiveFunction = memoize(expensiveFunction); console.log(memoizedExpensiveFunction(5)); //Output: computing... 10; console.log(memoizedExpensiveFunction(5)); //Output: 10 (cached) """ **Don't Do This:** Memoize functions unnecessarily, or use a cache that grows unbounded. Also make sure to select appropriate keys and implement correct cache invalidation if applicable. ### 5.4. Optimize Loops and DOM Manipulations **Standard:** Write efficient loops and minimize DOM manipulations. **Why:** Improve runtime performance and reduce browser reflows. **Do This:** * Use "for" or "while" loops instead of "forEach" for performance-critical sections. * Cache DOM element references. * Use "DocumentFragment" to perform multiple DOM manipulations at once. """javascript // Example using DocumentFragment const fragment = document.createDocumentFragment(); const list = document.getElementById('myList'); for (let i = 0; i < 100; i++) { const li = document.createElement('li'); li.textContent = "Item ${i}"; fragment.appendChild(li); } list.appendChild(fragment); // Single DOM manipulation """ **Don't Do This:** Perform excessive DOM manipulations in a loop, or use inefficient loop constructs. ### 5.5 Use correct data structures **Standard:** Utilize correct data structures given the problem context. Why: Improved data operation efficiency and improves code clarity. Do This: * Use "Maps" when needing to preserve insertion order or if keys are complex data types. * Use "Sets" when you need to work with unique values and fast membership checks. * Use "Arrays" for ordered collections of values, especially where index-based access matters. """javascript // Using Maps const myMap = new Map(); myMap.set('name', 'John'); myMap.set(1, 'Number One'); console.log(myMap.get('name')); // Output: John console.log(myMap.get(1)); // Output: Number One // Using Sets const mySet = new Set(); mySet.add(1); mySet.add(5); mySet.add(5); // Add duplicate item console.log(mySet.has(1)); // Output: true console.log(mySet.size); // Output: 2 """ Don't Do This: Don't default always to using plain objects or arrays. Consider the advantages that modern data structures like Maps and Sets bring. This document provides a solid foundation for establishing JavaScript coding standards focusing on core architecture. It's important to adapt and extend these guidelines to suit the specific needs and context of your project. Consistent application of these standards will lead to more maintainable, performant, and secure JavaScript applications.
# Code Style and Conventions Standards for JavaScript This document outlines the coding style and conventions standards for JavaScript development, aiming to promote consistency, readability, and maintainability across all projects. These standards leverage modern JavaScript (ES2024 and beyond) features and best practices. This document is intended to guide developers and inform AI coding assistants. ## 1. General Principles ### 1.1. Consistency * **Do This:** Adhere strictly to the guidelines outlined in this document. * **Don't Do This:** Introduce personal stylistic preferences that deviate from these standards unless justified by a specific technical need and approved by the team. **Why:** Consistent code is easier to read, understand, and maintain. It reduces cognitive load and makes collaboration more efficient. ### 1.2. Readability * **Do This:** Write code that is easily understandable by other developers (and your future self). Use meaningful variable names, consistent indentation, and clear comments. Prioritize clarity over brevity. * **Don't Do This:** Write overly complex or obfuscated code. Avoid clever tricks that sacrifice readability for minimal performance gains. **Why:** Readability is paramount. Well-readable code reduces the likelihood of errors and makes debugging and maintenance faster. ### 1.3. Maintainability * **Do This:** Design code that is modular, testable, and easy to modify or extend. Follow established design principles like DRY (Don't Repeat Yourself) and SOLID. * **Don't Do This:** Create tightly coupled, monolithic code that is difficult to refactor or reuse. **Why:** Maintainable code reduces the long-term cost of ownership. It allows for efficient bug fixes, feature additions, and technology upgrades. ### 1.4. Use of Modern JavaScript Features * **Do This:** Prefer modern ES2024 (and beyond) features such as "async/await", arrow functions, "const" and "let", class syntax, destructuring, spread syntax, and optional chaining. * **Don't Do This:** Rely on older, less readable syntax like "var", "function" keyword when arrow functions are appropriate, and verbose conditional checks. **Why:** Modern JavaScript features often provide more concise, readable, and performant solutions. They also improve code safety and reduce the likelihood of errors. ## 2. Formatting ### 2.1. Indentation * **Do This:** Use 2 spaces for indentation. Avoid tabs. * **Don't Do This:** Mix spaces and tabs or use inconsistent indentation. **Why:** Consistent indentation improves readability and visual structure. Two spaces are widely accepted and provide a good balance between nesting visibility and line length. """javascript // Correct indentation function processData(data) { if (data) { console.log("Data:", data); } } // Incorrect indentation function processData(data) { if (data) { console.log("Data:", data); } } """ ### 2.2. Line Length * **Do This:** Limit lines to a maximum of 80-120 characters. Break long lines for readability. * **Don't Do This:** Allow lines to exceed the maximum length, making code difficult to read on smaller screens or IDEs. **Why:** Reasonable line length keeps code readable and prevents horizontal scrolling, especially when viewing code side-by-side or in a code review tool. """javascript // Correct line length const formattedMessage = "This is a long message that wraps to the next line to improve readability and maintain a reasonable line length."; // Incorrect line length const formattedMessage = "This is a very long message that does not wrap and exceeds the recommended line length making it difficult to read."; """ ### 2.3. Whitespace * **Do This:** Use whitespace strategically to improve readability: * Add a space after commas and colons. * Add a space around operators (e.g., "=", "+", "-", "*", "/"). * Add blank lines to separate logical blocks of code. * Add a newline at the end of each file. * **Don't Do This:** Use excessive or inconsistent whitespace, which can make code harder to scan. **Why:** Consistent spacing improves visual clarity and makes code easier to parse.. """javascript // Correct whitespace const sum = a + b; const person = { name: "John", age: 30 }; if (isValid) { console.log("Valid"); } // Incorrect whitespace const sum=a+b; const person={name:"John",age:30}; if(isValid){ console.log("Valid"); } """ ### 2.4. Braces * **Do This:** Use braces for all control flow statements (e.g., "if", "else", "for", "while") even if the block contains only one statement. Place the opening brace on the same line as the statement. * **Don't Do This:** Omit braces for single-line blocks, as this can lead to errors and reduce readability. **Why:** Explicit braces improve readability and prevent potential errors when adding statements to a block. """javascript // Correct braces if (isValid) { console.log("Valid"); } else { console.log("Invalid"); } // Incorrect braces if (isValid) console.log("Valid"); // Avoid this else console.log("Invalid"); // Avoid this """ ### 2.5. Semicolons * **Do This:** Always use semicolons to terminate statements. Relying on automatic semicolon insertion (ASI) can lead to unexpected behavior. * **Don't Do This:** Omit semicolons at the end of statements, especially assignment ones. **Why:** Explicit semicolons ensure that statements are interpreted correctly and prevent potential errors caused by ASI. """javascript // Correct semicolons const message = "Hello"; console.log(message); // Incorrect semicolons (potential issue with ASI) const message = "Hello" console.log(message) """ ## 3. Naming Conventions ### 3.1. General Naming * **Do This:** * Use descriptive and meaningful names. * Avoid single-letter variable names (except in simple loop counters). * Use camelCase for variables and function names. * Use PascalCase for class names and constructor functions. * Use SCREAMING_SNAKE_CASE for constants. * **Don't Do This:** * Use ambiguous or abbreviated names. * Use names that conflict with reserved keywords. * Use inconsistent naming conventions. **Why:** Clear and consistent naming improves readability and makes it easier to understand the purpose of variables, functions, and classes. """javascript // Correct naming const userName = "John Doe"; function calculateTotal(price, quantity) { return price * quantity; } class Product { constructor(name, price) { this.name = name; this.price = price; } } const MAX_VALUE = 100; // Incorrect naming const a = "John Doe"; // Avoid function calc(p, q) { // Avoid return p * q; } """ ### 3.2. Variable Naming * **Do This:** Use noun or noun phrase for variables. * **Don't Do This:** Use verbs in variable names (unless they are boolean variables). **Why:** Variable names should clearly indicate what the variable *represents*. """javascript // Correct variable naming const userAge = 30; const productList = []; let isValidUser = true; // Boolean // Incorrect variable naming let calculate = 10; // Avoid - use a noun let adding = true; // Avoid - use 'isAdding' if boolean """ ### 3.3. Function Naming * **Do This:** Use verb or verb phrase for function names. * **Don't Do This:** Use nouns in function names. **Why:** Function names should clearly indicate what the function *does*. """javascript // Correct function naming function calculateArea(width, height) { return width * height; } function isValidEmail(email) { //Email validation logic return true; } // Incorrect function naming function area(width, height) { // Vague, not descriptive return width * height; } """ ### 3.4. Boolean Variables and Functions * **Do This:** Prefix boolean variable and function names with "is", "has", or "are". * **Don't Do This:** Use ambiguous names that do not clearly indicate a boolean value. **Why:** Consistent naming for boolean variables improves readability and reduces ambiguity. """javascript // Correct boolean naming let isValid = true; function hasPermission(user) { return user.permissions.includes("admin"); } // Incorrect boolean naming let valid = true; // Avoid function permission(user) { // Avoid return user.permissions.includes("admin"); } """ ## 4. Stylistic Consistency ### 4.1. Quotes * **Do This:** Use single quotes ("'") for string literals unless the string contains single quotes itself, in which case use template literals or double quotes ("""). * **Don't Do This:** Mix single and double quotes inconsistently. **Why:** Consistency improves readability. Single quotes are slightly easier to type and are generally preferred. Template literals offer additional functionality like string interpolation. """javascript // Correct quotes const name = 'John Doe'; const message = "He said, 'Hello!'"; const greeting = "Hello, ${name}!"; const path = 'c:\\path\\to\\file'; // Incorrect quotes const name = "John Doe"; // Inconsistent """ ### 4.2. Arrow Functions vs. Function Declarations * **Do This:** Prefer arrow functions ("=>") for concise, non-method functions. Use function declarations ("function") for named functions and methods within classes. * **Don't Do This:** Use arrow functions for complex functions with multiple statements or for methods that require "this" to refer to the class instance. **Why:** Arrow functions provide a more concise syntax and lexically bind "this". Function declarations are more suitable for named functions and methods that require "this" to refer to the object. """javascript // Correct arrow functions and function declarations const add = (a, b) => a + b; // Concise arrow function function multiply(a, b) { // Named function return a * b; } class Calculator { add(a, b) { // Method using function declaration return a + b; } } // Incorrect use of arrow function const calculator = { value:0, add: (a) => {this.value += a;} // WRONG: this will not refer to calculator } """ ### 4.3. Object and Array Literals * **Do This:** Use concise object and array literals: * Use shorthand property names (e.g., "{ name }" instead of "{ name: name }"). * Use spread syntax ("...") to copy or merge objects and arrays. * **Don't Do This:** Use verbose or outdated syntax for creating objects and arrays. **Why:** Concise literals improve readability and reduce boilerplate code. """javascript // Correct object and array literals const name = "John Doe"; const age = 30; const person = { name, age }; // Shorthand property names const numbers = [1, 2, 3]; const moreNumbers = [...numbers, 4, 5]; // Spread syntax // Incorrect object and array literals const personOld = { name: name, age: age }; // Verbose const moreNumbersOld = numbers.concat([4,5]); // Inefficient """ ### 4.4. Ternary Operators * **Do This:** Use ternary operators ("condition ? value1 : value2") for simple conditional assignments. * **Don't Do This:** Use ternary operators for complex logic or nested conditions, as this can reduce readability. Prefer "if/else" statements for complex conditions. **Why:** Ternary operators provide a concise syntax for simple conditions. However, complex ternary expressions can be difficult to understand and maintain. """javascript // Correct ternary operator const status = isValid ? "Active" : "Inactive"; // Incorrect ternary operator (too complex) const result = (a > b) ? (a > c ? a : c) : (b > c ? b : c); // Difficult understand. Avoid this! """ ## 5. Specific Code Examples and Patterns ### 5.1. Asynchronous Programming with "async/await" * **Do This:** Prefer "async/await" over callbacks and promises for asynchronous operations. * **Don't Do This:** Use deeply nested callbacks (callback hell) or neglect error handling in asynchronous code. **Why:** "async/await" makes asynchronous code easier to read and reason about. It also simplifies error handling with "try/catch" blocks. """javascript // Correct async/await async function fetchData() { try { const response = await fetch("https://api.example.com/data"); const data = await response.json(); return data; } catch (error) { console.error("Error fetching data:", error); throw error; // Re-throw the error to be handled upstream } } // Incorrect callbacks example (callback hell) function fetchDataOld(callback) { fetch("https://api.example.com/data") .then(response => response.json()) .then(data => { callback(data); }) .catch(error => { //Note: this will not handle errors thrown _inside_ the callback. console.error("Error fetching data:", error); }); } """ ### 5.2. Error Handling * Compile-time validation errors that might arise due to coding mistakes, must be handled gracefully and informative error messages should be displayed to the end-user. * **Do This:** Implement robust error handling using "try/catch" blocks and "finally" blocks. Handle errors at the appropriate level, either by logging them, displaying user-friendly messages, or re-throwing them for higher-level handling. * **Don't Do This:** Ignore errors or re-throw them without providing context. Don't rely solely on unhandled promise rejections. **Why:** Proper error handling prevents unexpected crashes and provides valuable information for debugging and maintenance. """javascript // Correct error handling async function processData(input) { try { // Validate input if (!input) { throw new Error("Input cannot be null or undefined."); } // Some code that can throw error... const result = await someAsyncOperation(input); return result; } catch (error) { console.error("Error processing data:", error.message); // Re-throw the error for higher-level handling throw new Error("Failed to process input data.", { cause: error }); } finally { // Clean up resources. This will always execute even if the try block throws. } } // Incorrect error handling async function processDataBad(input) { const result = await someAsyncOperation(input) // What if it throws? No try/catch. return result; //We might not reach here...but no error reporting! } """ ### 5.3. Module Imports and Exports * **Do This:** Use ES module syntax ("import" and "export") for organizing code into reusable modules. * **Don't Do This:** Use CommonJS ("require" and "module.exports") unless required maintaining compatibility with older environments. **Why:** ES modules provide a standardized and more efficient way to organize and load code compared to CommonJS. """javascript // Correct ES modules // file: utils.js export function add(a, b) { return a + b; } export const PI = 3.14159; // file: main.js import { add, PI } from "./utils.js"; console.log(add(2, 3)); console.log(PI); // Incorrect CommonJS // utils.js // module.exports = { // add: function(a, b) { return a + b; }, // PI: 3.14159 // }; // main.js // const utils = require('./utils'); // console.log(utils.add(2, 3)); // console.log(utils.PI); """ ### 5.4. Immutability * **Do This:** Favor immutability, especially when working with data transformations. Use methods like "map", "filter", "reduce", and the spread syntax to create new objects and arrays instead of modifying existing ones directly. * **Don't Do This:** Mutate objects and arrays directly, which can lead to unexpected side effects and make debugging more difficult. **Why:** Immutability makes code easier to reason about and test. It also prevents unintended side effects and enables more efficient change detection. """javascript // Correct immutability const numbers = [1, 2, 3]; const squaredNumbers = numbers.map(num => num * num); // Create a new array const newNumbers = [...numbers, 4]; // Create a new array // Incorrect mutation const numbersBad = [1, 2, 3]; numbersBad.push(4); // Mutates the original array! Avoid! """ ### 5.5. Use of "const" and "let" * **Do This:** Use "const" for variables that should not be reassigned after their initial value. Use "let" for variables that need to be reassigned. Avoid using "var". * **Don't Do This:** Use "var" in modern JavaScript code. Use "let" when "const" is more appropriate. **Why:** "const" and "let" provide block scope and improve code clarity. Using "const" signals that a variable's value should not change, which helps prevent accidental reassignments. "var" has function scope, which can lead to unexpected behavior. """javascript // Correct use of const and let const userName = "John"; // Value should not change let age = 30; // Value may change age = 31; // OK // Incorrect use of var var message = "Hello"; // Avoid function example() { var x = 10; if (true) { var x = 20; // Oops! Overwrites the outer x (function scope) console.log(x); // 20 } console.log(x); // 20 (unexpected) } example(); """ ### 5.6 Classes and Object-Oriented Programming * **Do This:** Use ES6 class syntax ("class") for creating objects and using object oriented-programming paradigms. * **Don't Do This:** Use older approaches to creating class-like structures. **Why:** ES6 Classes provide a clean syntax and structure for creating objects. """javascript // Correct use of Classes class Animal { constructor(name, sound) { this.name = name; this.sound = sound; } makeSound() { console.log(this.sound); } } const dog = new Animal('dog','woof'); dog.makeSound(); """ ### 5.7 Documentation and Comments * **Do This:** Add comments to explain complex logic, non-obvious code, and the purpose of functions and modules. Use JSDoc syntax liberally. * **Don't Do This:** Write excessive comments that simply reiterate what the code already does. """javascript /** * Calculates the area of a rectangle. * @param {number} width The width of the rectangle. * @param {number} height The height of the rectangle. * @returns {number} The area of the rectangle. */ function calculateArea(width, height) { // Multiply width and height to get the area return width * height; } """ ### 5.8 Testing * **Do This:** Write unit tests for every function and class. Aim for high code coverage. * **Don't Do This:** Skip testing or write superficial tests that don't thoroughly validate the code. """javascript // Example with Jest test('adds 1 + 2 to equal 3', () => { expect(1 + 2).toBe(3); }); """ ### 5.9 Security Practices * **Do This:** Sanitize user inputs. Use HTTPS. Prevent Cross-Site Scripting and SQL Injection attacks. Regularly update dependencies for security patches. * **Don't Do This:** Store sensitive information in client-side code. Neglect security best practices. These coding standards are designed to ensure the JavaScript code is consistent, readable, and maintainable. Adhering to these guidelines will make collaboration easier and reduce the likelihood of errors. All developers should follow these conventions and continually strive to improve the quality of code.
# Code Style and Conventions Standards for TypeScript This document outlines coding style and conventions standards for TypeScript development. Adhering to these standards promotes code consistency, readability, maintainability, and collaboration within development teams. These guidelines are tailored for the latest version of TypeScript and aim to leverage modern best practices. ## 1. Formatting Consistent formatting is crucial for readability. We adopt the following standards for TypeScript code formatting: ### 1.1. Whitespace and Indentation * **Standard:** Use 2 spaces for indentation. Avoid tabs. * **Why:** Consistent indentation enhances readability and reduces visual clutter. * **Do This:** """typescript function calculateArea(width: number, height: number): number { const area = width * height; return area; } """ * **Don't Do This:** """typescript function calculateArea(width: number, height: number): number { const area = width * height; return area; } """ * **Standard:** Use blank lines to separate logical sections of code within functions and classes. * **Why:** Separating logical blocks improves code comprehension. * **Do This:** """typescript function processData(data: any[]): void { // Validate data if (!data || data.length === 0) { throw new Error("Data is invalid."); } // Transform data const transformedData = data.map(item => ({ ...item, processed: true, })); // Save data saveToDatabase(transformedData); } """ ### 1.2. Line Length * **Standard:** Limit lines to a maximum of 120 characters. * **Why:** Enforces readability on various screen sizes and IDE configurations. * **How:** Configure your editor or IDE to display a line length guide at 120 characters. Break long lines at logical points, such as after commas, operators, or before opening parentheses. * **Do This:** """typescript const veryLongVariableName = calculateSomethingComplicated( param1, param2, param3 ); """ * **Don't Do This:** """typescript const veryLongVariableName = calculateSomethingComplicated(param1, param2, param3); """ ### 1.3. Braces and Parentheses * **Standard:** Use braces for all control flow statements, even single-line statements. * **Why:** Improves code clarity and reduces potential errors when modifying code. * **Do This:** """typescript if (isValid) { console.log("Valid"); } else { console.log("Invalid"); } """ * **Don't Do This:** """typescript if (isValid) console.log("Valid"); else console.log("Invalid"); """ * **Standard:** Use parentheses to clarify operator precedence, where needed. * **Why:** Reduces ambiguity, especially in complex expressions. * **Example:** """typescript const result = (a + b) * c; """ ### 1.4. Semicolons * **Standard:** Always use semicolons to terminate statements. * **Why:** Prevents unexpected behavior due to JavaScript's automatic semicolon insertion (ASI). * **Do This:** """typescript const name = "John"; console.log(name); """ * **Don't Do This:** """typescript const name = "John" console.log(name) """ ## 2. Naming Conventions Consistent naming conventions are essential for code clarity and maintainability. ### 2.1. Variables and Constants * **Standard:** Use camelCase for variable and constant names. * **Why:** Widely adopted convention for JavaScript and TypeScript. * **Do This:** """typescript const userName = "Alice"; let itemCount = 0; """ * **Standard:** Use UPPER_SNAKE_CASE for constant values (i.e. values that may be inlined for performance or are known at compile time). * **Why:** Clearly distinguishes constants from variables. * **Do This:** """typescript const MAX_RETRIES = 3; const API_ENDPOINT = "https://example.com/api"; """ ### 2.2. Functions and Methods * **Standard:** Use camelCase for function and method names. * **Why:** Follows common JavaScript/TypeScript conventions. * **Do This:** """typescript function calculateTotal(price: number, quantity: number): number { return price * quantity; } class ShoppingCart { addItem(item: string): void { console.log("Adding ${item} to the cart."); } } """ ### 2.3. Classes and Interfaces * **Standard:** Use PascalCase for class and interface names. * **Why:** Clearly identifies classes and interfaces. * **Do This:** """typescript interface User { id: number; name: string; } class Product { constructor(public name: string, public price: number) {} } """ ### 2.4. Type Parameters * **Standard:** Use single uppercase letters, typically "T", "U", "V", etc., for generic type parameters. * **Why:** Follows established TypeScript conventions. * **Do This:** """typescript function identity<T>(arg: T): T { return arg; } """ ### 2.5. Boolean Variables * **Standard:** Prefix boolean variables with "is", "has", or "should" to indicate a boolean value. * **Why:** Improves readability by clearly indicating the purpose of the variable. * **Do This:** """typescript let isValid: boolean = true; let hasPermission: boolean = false; let shouldUpdate: boolean = true; """ ## 3. Stylistic Consistency Consistency in style is critical for code maintainability. ### 3.1. Type Annotations and Inference * **Standard:** Use explicit type annotations where type inference is not obvious, especially for function parameters and return types. * **Why:** Improves code clarity and helps catch type-related errors early. * **Do This:** """typescript function greet(name: string): string { return "Hello, ${name}!"; } const add: (x: number, y: number) => number = (x, y) => x + y; """ * **Don't Do This:** """typescript function greet(name) { // Implicit 'any' type return "Hello, ${name}!"; } """ * **Standard:** Leverage type inference for local variables when the type is immediately apparent. * **Why:** Reduces verbosity and keeps code concise. * **Do This:** """typescript const message = "Hello, world!"; // Type inferred as string const count = 10; // Type inferred as number """ * **Standard:** When initializing variables with "null" or "undefined", explicitly define the type. * **Why:** Helps avoid unexpected type-related issues later. * **Do This:** """typescript let user: User | null = null; let data: string[] | undefined = undefined; """ ### 3.2. String Usage * **Standard:** Prefer template literals for string concatenation and multi-line strings. * **Why:** More readable and easier to maintain compared to traditional string concatenation. * **Do This:** """typescript const name = "Alice"; const message = "Hello, ${name}!"; const multiLine = "This is a multi-line string."; """ * **Don't Do This:** """typescript const name = "Alice"; const message = "Hello, " + name + "!"; const multiLine = "This is a\n" + "multi-line string."; """ ### 3.3. Object Literals * **Standard:** Use shorthand notation for object properties when the property name matches the variable name. * **Why:** Improves code conciseness and readability. * **Do This:** """typescript const name = "Alice"; const age = 30; const user = { name, age }; // Shorthand notation """ * **Don't Do This:** """typescript const name = "Alice"; const age = 30; const user = { name: name, age: age }; """ * **Standard:** Use object spread syntax for creating copies of objects or merging objects. * **Why:** More concise and readable than older methods like "Object.assign()". * **Do This:** """typescript const original = { a: 1, b: 2 }; const copy = { ...original, c: 3 }; // Creates a new object with a, b, and c """ ### 3.4. Arrow Functions * **Standard:** Use arrow functions for concise function expressions, especially for callbacks and inline functions. * **Why:** More compact syntax and lexically binds "this". * **Do This:** """typescript const numbers = [1, 2, 3]; const squared = numbers.map(x => x * x); // Concise arrow function """ * **Don't Do This:** """typescript const numbers = [1, 2, 3]; const squared = numbers.map(function(x) { return x * x; }); """ * **Standard:** Omit parentheses for single-parameter arrow functions. * **Why:** Makes the code even more concise. * **Do This:** """typescript const increment = x => x + 1; """ * **Don't Do This:** """typescript const increment = (x) => x + 1; """ ### 3.5. Modern TypeScript Features * **Standard:** Leverage features like optional chaining ("?.") and nullish coalescing ("??") for safer and more concise code. Optional properties on interfaces may be relevant if these are in use. * **Why:** Reduces boilerplate and improves null/undefined handling. * **Do This:** """typescript interface User { profile?: { address?: { city?: string; } } } const user: User = {}; const city = user?.profile?.address?.city ?? "Unknown"; // Nullish coalescing console.log(city); interface Config { timeout?: number; } const defaultConfig: Config = { timeout: 5000, }; function initialize(config?: Config) { const timeout = config?.timeout ?? defaultConfig.timeout; console.log("Timeout: ${timeout}"); } initialize(); // Timeout: 5000 initialize({ timeout: 10000 }); // Timeout: 10000 """ * **Standard:** Utilize discriminated unions and exhaustive checks for increased type safety and maintainability. * **Why:** Improves type correctness and makes it easier to handle different states or object types. * **Do This:** """typescript interface Success { type: "success"; result: any; } interface Error { type: "error"; message: string; } type Result = Success | Error; function handleResult(result: Result) { switch (result.type) { case "success": console.log("Success:", result.result); break; case "error": console.error("Error:", result.message); break; default: // Exhaustive check: TypeScript will flag this if a new type is added to Result const _exhaustiveCheck: never = result; return _exhaustiveCheck; } } const successResult: Success = { type: "success", result: { data: "example" } }; const errorResult: Error = { type: "error", message: "Something went wrong" }; handleResult(successResult); handleResult(errorResult); """ ### 3.6. Asynchronous Code * **Standard:** Always use "async/await" syntax for asynchronous operations. * **Why:** Improves readability and simplifies error handling compared to traditional promise chains. * **Do This:** """typescript async function fetchData(): Promise<any> { try { const response = await fetch("https://example.com/api/data"); const data = await response.json(); return data; } catch (error) { console.error("Error fetching data:", error); throw error; } } """ * **Don't Do This:** """typescript function fetchData(): Promise<any> { return fetch("https://example.com/api/data") .then(response => response.json()) .then(data => data) .catch(error => { console.error("Error fetching data:", error); throw error; }); } """ * **Standard:** Use "Promise.all" for concurrent asynchronous operations that don't depend on each other. * **Why:** Improves performance by executing asynchronous tasks in parallel. * **Do This:** """typescript async function processData(): Promise<void> { const [result1, result2] = await Promise.all([ fetchData1(), fetchData2(), ]); console.log("Result 1:", result1); console.log("Result 2:", result2); } """ ### 3.7 Error Handling * **Standard:** Implement robust error handling using "try...catch" blocks, especially in asynchronous functions. * **Why:** Prevents unhandled exceptions and allows for graceful recovery. * **Do This:** """typescript async function doSomething() { try { const result = await someAsyncOperation(); console.log("Result:", result); } catch (error) { console.error("An error occurred:", error); // Implement specific error handling/logging } } """ * **Standard:** Create custom error classes to provide more context and specify error handling logic. * **Why:** Extends the built-in Error to communicate more specific information about the error to the outside world. * **Do This:** """typescript class CustomError extends Error { constructor(message: string, public errorCode: number) { super(message); this.name = "CustomError"; Object.setPrototypeOf(this, CustomError.prototype); } } async function performOperation() { try { // some operation throw new CustomError("Operation failed", 500); } catch (error) { if (error instanceof CustomError) { console.error("Custom Error ${error.errorCode}: ${error.message}"); } else { console.error("An unexpected error occurred:", error); } } } """ ### 3.8 Immutability * **Standard:** Strive for immutability whenever practical, using "const" for variables that should not be reassigned and avoiding direct modification of objects and arrays. * **Why:** Makes code more predictable and easier to reason about, reducing the risk of bugs. * **Do This:** """typescript const originalArray = [1, 2, 3]; const newArray = [...originalArray, 4]; // Creates a new array const originalObject = { a: 1, b: 2 }; const newObject = { ...originalObject, c: 3 }; // Creates a new object """ * **Don't Do This:** """typescript const originalArray = [1, 2, 3]; originalArray.push(4); // Modifies the original array const originalObject = { a: 1, b: 2 }; originalObject.c = 3; // Modifies the original object """ ### 3.9 Comments * **Standard:** Add comments to explain complex or non-obvious logic, but prioritize writing self-documenting code. * **Why:** Comments should supplement, not replace, clear code. * **Guidelines:** * Use JSDoc-style comments for documenting functions, classes, and interfaces. * Explain the *why*, not the *what*. The code should explain what it does. * Keep comments concise and up-to-date. * Remove outdated or redundant comments. * **Example:** """typescript /** * Calculates the area of a rectangle. * @param width The width of the rectangle. * @param height The height of the rectangle. * @returns The area of the rectangle. */ function calculateArea(width: number, height: number): number { return width * height; } """ ## 4. Technology Specific Details (Distinguishing Good from Great) * **Standard:** Take advantage of TypeScript's advanced type features to create robust and maintainable code structures. * **Guidelines:** * **Utility Types:** Employ TypeScript's utility types ("Partial", "Readonly", "Pick", "Omit", "Record", etc.) to manipulate types and generate new types efficiently. """typescript interface User { id: number; name: string; email: string; age: number; } // Make all properties optional type PartialUser = Partial<User>; // Make specified properties required type RequiredIdAndName = Required<Pick<User, 'id' | 'name'>>; // Type with only certain properties type UserInfo = Pick<User, 'name' | 'email'>; // Type without certain properties type UserWithoutId = Omit<User, 'id'>; """ * **Mapped Types:** Utilize mapped types to transform the properties of an existing type, providing a dynamic way to define new types based on existing ones. """typescript interface Product { id: string; name: string; price: number; } // Create a read-only version of Product type ReadonlyProduct = Readonly<Product>; // Create a type where all properties of Product are nullable type NullableProduct = { [K in keyof Product]: Product[K] | null; }; """ * **Conditional Types:** Conditional types allow to define types based on conditions, adding yet another powerful layer of abstraction to type definitions. They help to ensure type safety throughout an application. """typescript type NonNullableProperty<T, K extends keyof T> = T[K] extends null | undefined ? never : K; type RequiredProperties<T> = Pick<T, NonNullableProperty<T, keyof T>>; interface Configuration { host?: string; port?: number; // Port can be potentially undefined or null timeout?: number; } // Extracts properties that are guaranteed to be assigned during runtime. type RuntimeProperties = RequiredProperties<Configuration>; // Result equivalent to {timeout: number;} """ * **Decorators:** Use decorators to add metadata or modify the behavior of classes, methods, properties, or parameters. * **Why:** Provide a declarative and reusable way to add functionality, such as logging, validation, or dependency injection. * **Example:** """typescript function logMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor) { const originalMethod = descriptor.value; descriptor.value = function(...args: any[]) { console.log("Calling method ${propertyKey} with arguments: ${JSON.stringify(args)}"); const result = originalMethod.apply(this, args); console.log("Method ${propertyKey} returned: ${result}"); return result; }; return descriptor; } class Calculator { @logMethod add(a: number, b: number): number { return a + b; } } const calculator = new Calculator(); calculator.add(2, 3); // Output: // Calling method add with arguments: [2,3] // Method add returned: 5 """ ## 5. Tooling * **Standard:** Use Prettier for automatic code formatting and ESLint with recommended TypeScript rules for linting. * **Why:** Automates formatting and enforces code quality, reducing manual effort and improving consistency. * **Configuration:** Configure Prettier and ESLint to work seamlessly with your IDE and CI/CD pipeline. * **Example ".eslintrc.js" configuration:** """javascript module.exports = { parser: "@typescript-eslint/parser", parserOptions: { ecmaVersion: 2020, sourceType: "module", project: './tsconfig.json', }, plugins: ["@typescript-eslint"], extends: [ "eslint:recommended", "plugin:@typescript-eslint/recommended", "plugin:@typescript-eslint/recommended-requiring-type-checking", "prettier", ], rules: { // Add or override rules here }, }; """ By adhering to these coding standards, TypeScript projects will benefit from improved code quality, readability, and maintainability, fostering a collaborative and productive development environment.
# Component Design Standards for JavaScript This document outlines the component design standards for JavaScript, focusing on creating reusable, maintainable, and performant components. It leverages modern JavaScript features and best practices to ensure high-quality code. ## 1. Component Abstraction and Reusability ### 1.1 Standard: Encapsulation and Information Hiding **Do This:** * Encapsulate component logic and state within the component. * Use closures or WeakMaps to hide internal implementation details and prevent external modification. * Expose only a minimal, well-defined public API. **Don't Do This:** * Directly modify internal component state from outside. * Expose unnecessary implementation details in the public API. **Why:** Encapsulation reduces dependencies and makes components easier to refactor and reuse without affecting other parts of the application. **Example:** """javascript // Good: Using closures for encapsulation const createCounter = () => { let count = 0; return { increment: () => { count++; return count; }, decrement: () => { count--; return count; }, getCount: () => count }; }; const counter = createCounter(); console.log(counter.increment()); // 1 console.log(counter.decrement()); // 0 console.log(counter.getCount()); // 0 // Attempting to directly modify "count" will not work // counter.count = 10; // This has no effect """ """javascript // Bad: Exposing internal state directly const Counter = () => { this.count = 0; this.increment = () => { this.count++; return this.count; }; this.decrement = () => { this.count--; return this.count; }; }; const counterInstance = new Counter(); console.log(counterInstance.increment()); // 1 counterInstance.count = 100; // Direct modification console.log(counterInstance.count); // 100 """ ### 1.2 Standard: Single Responsibility Principle (SRP) **Do This:** * Design components that have one, and only one, reason to change. * Break down complex components into smaller, focused components. **Don't Do This:** * Create "god components" that handle multiple unrelated responsibilities. **Why:** SRP simplifies component design, making them easier to understand, test, and maintain. **Example:** """javascript // Good: Separating concerns // Component: Displays user profile information const UserProfile = ({ user }) => { return ( <div> <h2>{user.name}</h2> <p>Email: {user.email}</p> <UserAddress address={user.address} /> </div> ); }; // Component: Displays user address const UserAddress = ({ address }) => { return ( <div> <h3>Address:</h3> <p>{address.street}</p> <p>{address.city}, {address.state} {address.zip}</p> </div> ); }; """ """javascript // Bad: Mixing concerns // Component: Displays user profile and address (bad SRP) const UserDetails = ({ user }) => { return ( <div> <h2>{user.name}</h2> <p>Email: {user.email}</p> <h3>Address:</h3> <p>{user.address.street}</p> <p>{user.address.city}, {user.address.state} {user.address.zip}</p> </div> ); }; """ ### 1.3 Standard: Parameterization and Configuration **Do This:** * Make components configurable through props or configuration objects. * Provide sensible defaults for optional parameters. * Use TypeScript interfaces or JSDoc to define the expected props. **Don't Do This:** * Hardcode values that should be configurable. * Rely on global state or side effects for component behavior. **Why:** Parameterization increases the flexibility and reusability of components across different contexts. **Example:** """javascript // Good: Configuring component via props /** * @typedef {Object} ButtonProps * @property {string} label - The text displayed on the button. * @property {string} [type='button'] - The button type (e.g., 'submit', 'reset'). * @property {function} onClick - The function to execute when the button is clicked. */ /** * Creates a button component. * @param {ButtonProps} props - The button properties. * @returns {HTMLButtonElement} - The button element. */ const Button = ({ label, type = 'button', onClick }) => { const handleClick = () => { onClick(); }; const buttonElement = document.createElement('button'); buttonElement.textContent = label; buttonElement.type = type; buttonElement.addEventListener('click', handleClick); return buttonElement; }; // Usage const myButton = Button({ label: 'Click Me', type: 'submit', onClick: () => console.log('Button clicked!') }); document.body.appendChild(myButton); """ """javascript // Bad: Hardcoding values const Button = () => { const buttonElement = document.createElement('button'); buttonElement.textContent = 'Click Me'; // Hardcoded buttonElement.type = 'button'; // Hardcoded buttonElement.addEventListener('click', () => { console.log('Button clicked!'); // Hardcoded }); return buttonElement; }; document.body.appendChild(Button()); """ ### 1.4 Standard: Avoid Global State and Side Effects **Do This:** * Design components as pure functions or with minimal side effects. * Manage state using dedicated state management libraries or component-local state. * Isolate side effects within specific lifecycle methods or effect hooks. **Don't Do This:** * Directly modify global variables or external state from within components. * Perform uncontrolled side effects that can impact other parts of the application. **Why:** Minimizing side effects makes components more predictable, testable, and easier to reason about. **Example:** """javascript // Good: Local component state import { useState } from 'react'; const Counter = () => { const [count, setCount] = useState(0); return ( <div> <p>Count: {count}</p> <button onClick={() => setCount(count + 1)}>Increment</button> </div> ); }; """ """javascript // Bad: Global state let globalCount = 0; const Counter = () => { const increment = () => { globalCount++; console.log('Global Count:', globalCount); }; return ( <div> <p>Count: {globalCount}</p> <button onClick={increment}>Increment</button> </div> ); }; """ ## 2. Component Composition and Patterns ### 2.1 Standard: Favor Composition over Inheritance **Do This:** * Build complex components by composing smaller, reusable components. * Use strategies like function composition or higher-order components to enhance functionality. **Don't Do This:** * Rely heavily on inheritance hierarchies, which can lead to tightly coupled and inflexible code. **Why:** Composition promotes loose coupling and allows for more flexible and dynamic component structures. **Example:** """javascript // Good: Composition const WithLogging = (WrappedComponent) => { return (props) => { console.log("Component ${WrappedComponent.name} is rendering"); return <WrappedComponent {...props} />; }; }; const MyComponent = () => { return <p>Hello from MyComponent!</p>; }; const LoggedComponent = WithLogging(MyComponent); """ """javascript // Bad: Inheritance (example in ES6 classes if required) class BaseComponent extends React.Component { logRendering() { console.log("Component is rendering"); } render() { this.logRendering(); return null; } } class MyComponent extends BaseComponent { render() { super.render(); return <p>Hello from MyComponent!</p>; } } """ ### 2.2 Standard: Render Props and Hooks **Do This:** * Use render props or hooks to share logic between components. * Create custom hooks to encapsulate reusable stateful logic. **Don't Do This:** * Duplicate logic across multiple components. **Why:** Render props and hooks allow for clean and reusable logic sharing, improving component maintainability. **Example:** """javascript // Good: Custom Hook import { useState, useEffect } from 'react'; const useWindowSize = () => { const [windowSize, setWindowSize] = useState({ width: window.innerWidth, height: window.innerHeight, }); useEffect(() => { const handleResize = () => { setWindowSize({ width: window.innerWidth, height: window.innerHeight, }); }; window.addEventListener('resize', handleResize); return () => { window.removeEventListener('resize', handleResize); }; }, []); return windowSize; }; const MyComponent = () => { const { width, height } = useWindowSize(); return ( <div> <p>Window Width: {width}</p> <p>Window Height: {height}</p> </div> ); }; """ ### 2.3 Standard: Design Patterns (e.g., Observer, Factory) **Do This:** * Implement appropriate design patterns to solve common component design problems. * Document the pattern usage clearly. **Don't Do This:** * Overuse patterns or apply them where simpler solutions are adequate. **Why:** Design patterns provide proven solutions to recurring problems, improving code structure and maintainability. **Example - Observer Pattern:** """javascript // Good: Observer Pattern class Subject { constructor() { this.observers = []; } subscribe(observer) { this.observers.push(observer); } unsubscribe(observer) { this.observers = this.observers.filter(obs => obs !== observer); } notify(data) { this.observers.forEach(observer => observer.update(data)); } } class Observer { constructor(name) { this.name = name; } update(data) { console.log("${this.name} received data: ${data}"); } } const subject = new Subject(); const observer1 = new Observer("Observer 1"); const observer2 = new Observer("Observer 2"); subject.subscribe(observer1); subject.subscribe(observer2); subject.notify("Hello, Observers!"); // Output to console from both observers """ ## 3. Component Styling and Theming ### 3.1 Standard: CSS-in-JS or CSS Modules **Do This:** * Use CSS-in-JS libraries or CSS Modules for component styling, encapsulating styles within the component. * Avoid global CSS styles that can cause conflicts. **Don't Do This:** * Use inline styles excessively, as they are difficult to maintain and reuse. **Why:** CSS-in-JS and CSS Modules improve component encapsulation and prevent style conflicts. **Example: Styled Components** """javascript // Good: Using Styled Components (CSS-in-JS) import styled from 'styled-components'; const StyledButton = styled.button" background-color: #4CAF50; border: none; color: white; padding: 15px 32px; text-align: center; text-decoration: none; display: inline-block; font-size: 16px; cursor: pointer; &:hover { background-color: #3e8e41; } "; const MyComponent = () => { return <StyledButton>Click me</StyledButton>; }; """ ### 3.2 Standard: Theming and Variable Usage **Do This:** * Use a theming solution (e.g., CSS variables, styled-components themes) to manage consistent styling across the application. * Define and use semantic variable names. **Don't Do This:** * Hardcode color values or font sizes throughout the codebase. **Why:** Theming improves consistency and simplifies style updates. **Example:** """javascript // Good: Using CSS Variables for Theming :root { --primary-color: #007bff; --secondary-color: #6c757d; --font-size-base: 16px; } .button { background-color: var(--primary-color); color: white; font-size: var(--font-size-base); padding: 10px 20px; border: none; } .button.secondary { background-color: var(--secondary-color); } """ ## 4. Component Testing ### 4.1 Standard: Unit Testing **Do This:** * Write unit tests for individual components to verify their behavior in isolation. * Use mocking or stubbing to isolate components from external dependencies. **Don't Do This:** * Skip unit tests for complex components. * Write tests that are too tightly coupled to the implementation details. **Why:** Unit tests ensure that components function correctly and prevent regressions during refactoring. **Example using Jest and React Testing Library:** """javascript // Good: Unit Test for a Counter Component import React from 'react'; import { render, fireEvent } from '@testing-library/react'; import Counter from './Counter'; test('increments counter when increment button is clicked', () => { const { getByText } = render(<Counter />); const incrementButton = getByText('Increment'); const countElement = getByText('Count: 0'); fireEvent.click(incrementButton); expect(getByText('Count: 1')).toBeInTheDocument(); }); """ ### 4.2 Standard: Integration Testing **Do This:** * Write integration tests to verify the interaction between multiple components. * Test the component within the context of its surroundings **Don't Do This:** * Only focus on unit tests and neglect integration tests **Why:** Integration tests ensure that components work together as expected and that the application functions correctly as a whole. ## 5. Component Performance ### 5.1 Standard: Memoization **Do This:** * Use "React.memo" or similar techniques to prevent unnecessary re-renders of components that receive the same props. * Consider using Reselect for memoizing derived data from state. **Don't Do This:** * Memoize components indiscriminately, as the memoization check itself has a cost. **Why:** Memoization can significantly improve performance by reducing the number of unnecessary renders. **Example:** """javascript // Good: memoization of a component import React from 'react'; const MyComponent = React.memo(({ data }) => { console.log('MyComponent is rendering'); // Only renders when props change return <p>Data: {data}</p>; }); export default MyComponent; """ ### 5.2 Standard: Lazy Loading **Do This:** * Use lazy loading to load components only when they are needed. * Implement code splitting to reduce the initial bundle size. **Don't Do This:** * Load all components upfront, which can slow down initial page load times. **Why:** Lazy loading improves initial load times and reduces the amount of code that needs to be downloaded by the browser. **Example:** """javascript // Good: Lazy Loading a Component import React, { lazy, Suspense } from 'react'; const LazyComponent = lazy(() => import('./LazyComponent')); const MyPage = () => { return ( <div> <h1>My Page</h1> <Suspense fallback={<div>Loading...</div>}> <LazyComponent /> </Suspense> </div> ); }; export default MyPage; """ ### 5.3 Standard: Virtualization **Do This:** * Use virtualization techniques (e.g., "react-window", "react-virtualized") for rendering large lists or tables. * Avoid rendering all elements in the list at once, which can cause performance issues. **Don't Do This:** * Render large lists or tables without virtualization. **Why:** Virtualization significantly improves performance when rendering large lists by only rendering the visible elements. ## 6. Accessibility ### 6.1 Standard: ARIA Attributes **Do This:** * Use ARIA attributes to provide semantic information about components for assistive technologies. * Ensure that components are keyboard accessible. **Don't Do This:** * Rely solely on visual cues to convey information. **Why:** ARIA attributes make components accessible to users with disabilities. **Example:** """javascript // Good: Using ARIA Attributes const AccessibleButton = ({ onClick, children }) => { return ( <button onClick={onClick} aria-label="Click to perform action"> {children} </button> ); }; """ ### 6.2 Standard: Semantic HTML **Do This:** * Use semantic HTML elements (e.g., "<article>", "<nav>", "<aside>") to structure components. * Provide appropriate labels and descriptions for form elements. **Don't Do This:** * Use "<div>" or "<span>" elements excessively without providing semantic meaning. **Why:** Semantic HTML improves accessibility and SEO by providing meaningful structure to the content. ## 7. Security Considerations ### 7.1 Standard: Input Validation and Sanitization **Do This:** * Validate and sanitize all user inputs to prevent script injection. * Use appropriate encoding techniques for displaying user-generated content. **Don't Do This:** * Directly render user-provided strings without sanitization. **Why:** Input validation and sanitization are crucial for preventing security vulnerabilities such as cross-site scripting (XSS). **Example:** """javascript // Escape HTML function escapeHTML(str) { let div = document.createElement('div'); div.appendChild(document.createTextNode(str)); return div.innerHTML; } const unsafeText = '<script>alert("XSS");</script>'; const safeText = escapeHTML(unsafeText); // Now safeText can be rendered without executing the script """ ### 7.2 Standard: Avoid eval() **Do This:** * Never use "eval()" or similar functions that execute arbitrary code from strings. **Why:** "eval()" can introduce dangerous security vulnerabilities by executing untrusted code. ### 7.3 Standard: Dependency Management **Do This:** * Keep all dependencies up-to-date to avoid known vulnerabilities. * Regularly audit dependencies for security issues using tools like "npm audit" or "yarn audit". ## 8. Error Handling ### 8.1 Standard: Centralized Error Handling **Do This:** * Implement Error Boundaries to catch JavaScript errors anywhere in the UI and log the errors. * Display a graceful fallback UI instead of crashing the component. **Don't Do This:** * Let errors propagate up to crash the entire application. **Why:** Error Boundaries improve the user experience by preventing the entire application from crashing due to errors in one part. **Example:** """javascript // Error Boundary Component class ErrorBoundary extends React.Component { constructor(props) { super(props); this.state = { hasError: false }; } static getDerivedStateFromError(error) { // Update state so the next render will show the fallback UI. return { hasError: true }; } componentDidCatch(error, errorInfo) { // You can also log the error to an error reporting service console.error(error, errorInfo); } render() { if (this.state.hasError) { // You can render any custom fallback UI return <h1>Something went wrong.</h1>; } return this.props.children; } } // Wrapping a component <ErrorBoundary> <MyComponent /> </ErrorBoundary> """ These standards cover best practices for component design in JavaScript, promoting reusability, maintainability, performance, and security. By adhering to these guidelines, developers can create high-quality, robust applications.