From 8c245e8dae2320efd9be0b77796acca238e12aff Mon Sep 17 00:00:00 2001 From: aveline Date: Tue, 22 Aug 2023 14:16:04 -0700 Subject: [PATCH 1/2] Create Code style guide.md First draft of code style guide Co-Authored-By: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com> --- documentation/Code style guide.md | 44 +++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 documentation/Code style guide.md diff --git a/documentation/Code style guide.md b/documentation/Code style guide.md new file mode 100644 index 00000000000..09515058e15 --- /dev/null +++ b/documentation/Code style guide.md @@ -0,0 +1,44 @@ +# `@shopify/polaris` Code Style Guide + +## Introduction + +The `@shopify/polaris` code style guide provides guidelines and best practices for writing consistent and maintainable code in the `@shopify/polaris` React component library. Adhering to this guide will help ensure code readability, consistency, and collaboration among developers. These guidelines are for items that are not enforced by automated tools like prettier, eslint, or stylelint-polaris + +## Table of Contents + +1. [Naming Conventions](#naming-conventions) +1. [Control Structures and Flow](#control-structures-and-flow) +1. [Error Handling](#error-handling) +1. [Code Organization and Structure]1#code-organization-and-structure) +1. [Examples and Code Snippets](#examples-and-code-snippets) + +## Naming Conventions + +- Use camel case for variable and function names. +- Use Pascal case for component names. +- Use Kebab case for props with a predefined list of strings. +- Use descriptive and meaningful names that accurately represent the purpose of the variable, function, or component. + +## Control Structures and Flow + +- Use early returns or guard clauses to handle exceptional cases and reduce nesting. + +## Error Handling + +- Use `try-catch` blocks to handle exceptions and errors. +- Provide meaningful error messages that help developers understand the issue. +- Log errors appropriately for debugging and troubleshooting purposes. + +## Code Organization and Structure + +- Organize code files and directories logically and consistently. +- Use meaningful and descriptive file and directory names. +- Follow the recommended folder structure for components, utilities, and tests. +- Import modules and components in alphabetical order. +- Group related functions and variables together within a file. +- Include JSDoc tags to describe default prop values + +## Examples and Code Snippets + +- Include examples and code snippets in the documentation to demonstrate usage and best practices. +- Provide clear and concise code examples that highlight the recommended coding style and patterns. From 229c2a54231d047bfd4173434952691c11a2cfbc Mon Sep 17 00:00:00 2001 From: aveline Date: Wed, 23 Aug 2023 08:52:57 -0700 Subject: [PATCH 2/2] Update documentation/Code style guide.md Co-authored-by: Sam Rose <11774595+samrose3@users.noreply.github.com> --- documentation/Code style guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/Code style guide.md b/documentation/Code style guide.md index 09515058e15..f0007330a8b 100644 --- a/documentation/Code style guide.md +++ b/documentation/Code style guide.md @@ -36,7 +36,7 @@ The `@shopify/polaris` code style guide provides guidelines and best practices f - Follow the recommended folder structure for components, utilities, and tests. - Import modules and components in alphabetical order. - Group related functions and variables together within a file. -- Include JSDoc tags to describe default prop values +- Include [JSDoc tags](https://jsdoc.app/) to describe default prop values ## Examples and Code Snippets