diff --git a/code-style.md b/code-style.md new file mode 100644 index 0000000000..5917d75856 --- /dev/null +++ b/code-style.md @@ -0,0 +1,46 @@ +# Code Style Guidelines + +## 1. Naming Conventions +- Use PascalCase for component names +- Use camelCase for variables and functions +- Use consistent naming conventions across the project + +## 2. Code Structure +- Use TypeScript for type safety and improved developer experience +- Use JSX syntax for React components +- Prefer functional components with hooks over class components +- Implement a modular file structure, grouping related components and exports in specific folders +- Use arrow functions for component definitions +- Organize imports at the top of files +- Use optional chaining (?.) for potentially undefined properties +- Prefer const over let for variable declarations +- Use default parameter values and optional parameters where appropriate +- Use interface or type aliases for complex object structures +- Use explicit return types for functions and components + +## 3. Documentation +- Use JSDoc-style comments for function and component documentation +- Provide detailed component descriptions, including parameter descriptions and example usage +- Use markdown formatting for documentation, including proper syntax for code blocks +- Use descriptive and concise titles for documentation sections +- Use consistent formatting for component documentation + +## 4. Error Handling +- Implement proper error handling and type checking +- Use async/await for asynchronous operations + +## 5. Performance +- Optimize component rendering using React performance optimization techniques +- Follow a modular approach by breaking down functionality into smaller, reusable components + +## 6. Security +- Use crypto.timingSafeEqual for secure string comparison +- Avoid using dangerouslySetInnerHTML to prevent XSS vulnerabilities +- Avoid using eval for security reasons +- Use hardcoded string literals when calling require to prevent potential vulnerabilities +- Use safe alternatives to manipulate DOM elements instead of innerHTML + +## 7. Best Practices +- Use proper indentation and spacing for improved readability +- Provide descriptive comments for functions and components +- Utilize TypeScript's type annotations \ No newline at end of file diff --git a/style-guide.md b/style-guide.md new file mode 100644 index 0000000000..848d324980 --- /dev/null +++ b/style-guide.md @@ -0,0 +1,95 @@ +# Style Guide + +This style guide provides guidelines for maintaining consistent, high-quality code and documentation across our project. By following these guidelines, we ensure better readability, maintainability, and collaboration among team members. + +## Table of Contents + +1. [Naming Conventions](#naming-conventions) +2. [Code Structure](#code-structure) +3. [Documentation](#documentation) +4. [Error Handling](#error-handling) +5. [Performance](#performance) +6. [Security](#security) + +## Naming Conventions + +### Use Clear and Descriptive Names + +- Choose meaningful names for variables, functions, and classes that accurately describe their purpose or functionality. +- Avoid abbreviations or cryptic names that may confuse other developers. + +### Ensure Consistency in Component Naming + +- Use correct and consistent import names for components across the project. +- Example: Use 'SignIn' instead of 'UserButton' for a sign-in component. + +## Code Structure + +### Maintain Consistent Formatting + +- Use consistent indentation and formatting throughout the codebase. +- Follow established coding style guidelines for the programming language being used. + +### Organize Imports and Components + +- Use appropriate imports from the correct packages (e.g., '@stackframe/stack'). +- Organize components into separate files or modules for better code organization and maintainability. + +## Documentation + +### Write Clear Comments + +- Provide clear and concise comments for complex code sections and functions. +- Explain the purpose and functionality of the code, not just restate what the code does. + +### Maintain Accurate Headers + +- Ensure header names and content in documentation are accurate and consistent. +- Use appropriate heading levels to create a clear hierarchy of information. + +### Create Meaningful Pull Request Descriptions + +- Write PR titles and bodies that directly address the documentation changes being made. +- Clearly explain the purpose and impact of the changes. + +### Link to Relevant Discussions + +- Include links to relevant discussions in Discord or other communication channels. +- Indicate where review and agreement on changes have taken place. + +### Ensure Accurate Code Snippets + +- Maintain up-to-date and accurate code snippets in documentation. +- Test code snippets to ensure they work as intended. + +### Include Visual Representations + +- Add visual representations (images) alongside code examples when appropriate. +- Use proper image references in Markdown format. +- Example: `![Sign-in Component](../imgs/sign-in.png)` + +## Error Handling + +### Implement Proper Error Handling + +- Implement appropriate error handling and logging mechanisms throughout the codebase. +- Catch and handle exceptions gracefully to prevent application crashes. +- Log errors with sufficient detail to aid in debugging and troubleshooting. + +## Performance + +### Optimize Critical Code Sections + +- Identify and optimize critical sections of code for better performance. +- Use profiling tools to identify bottlenecks and areas for improvement. +- Consider factors such as time complexity, memory usage, and resource utilization. + +## Security + +### Follow Secure Coding Practices + +- Adhere to best practices for secure coding to prevent common vulnerabilities. +- Implement proper input validation and sanitization. +- Use secure authentication and authorization mechanisms. +- Keep sensitive information, such as API keys and passwords, out of the codebase. +- Regularly update dependencies to address known security vulnerabilities. \ No newline at end of file