Skip to content

Latest commit

 

History

History
95 lines (60 loc) · 3.43 KB

style-guide.md

File metadata and controls

95 lines (60 loc) · 3.43 KB
Raw

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
  2. Code Structure
  3. Documentation
  4. Error Handling
  5. Performance
  6. 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.