Doc: Migrate naming conventions (#40781)

docs/quality-and-best-practices/css-sass-naming-conventions.md

@@ -0,0 +1,62 @@
+# CSS/Sass Naming Conventions
+
+Table of Contents:
+
+- [Introduction](#introduction)
+- [Prefixing](#prefixing)
+- [Class names](#class-names)
+    - [Example](#example)
+- [TL;DR](#tldr)
+  
+## Introduction
+
+Our guidelines are based on those used in [Calypso](https://github.com/Automattic/wp-calypso), which itself follows the [BEM methodology](https://getbem.com/).
+
+Refer to the [Calypso CSS/Sass Coding Guidelines](https://wpcalypso.wordpress.com/devdocs/docs/coding-guidelines/css.md) for full details.
+
+Read more about [BEM key concepts](https://en.bem.info/methodology/key-concepts/).
+
+There are a few differences in WooCommerce which are outlined below.
+
+## Prefixing
+
+As a WordPress plugin WooCommerce has to play nicely with WordPress core and other plugins/themes. To minimize conflict potential, all classes should be prefixed with `.woocommerce-`.
+
+## Class names
+
+When naming classes, remember:
+
+- **Block** - Standalone entity that is meaningful on its own. Such as the name of a component.
+- **Element** - Parts of a block and have no standalone meaning. They are semantically tied to its block.
+- **Modifier** - Flags on blocks or elements. Use them to change appearance or behavior.
+
+### Example
+
+```css
+/* Block */
+.woocommerce-loop {}
+
+/* Nested block */
+.woocommerce-loop-product {}
+
+/* Modifier */
+.woocommerce-loop-product--sale {}
+
+/* Element */
+.woocommerce-loop-product__link {}
+
+/* Element */
+.woocommerce-loop-product__button-add-to-cart {}
+
+/* Modifier */
+.woocommerce-loop-product__button-add-to-cart--added {}
+```
+
+**Note:** `.woocommerce-loop-product` is not named as such because the block is nested within `.woocommerce-loop`. It's to be specific so that we can have separate classes for single products, cart products, etc. **Nested blocks do not need to inherit their parents full name.**
+
+## TL;DR
+
+- Follow the [WordPress Coding standards for CSS](https://make.wordpress.org/core/handbook/best-practices/coding-standards/css/) unless it contradicts anything here.
+- Follow [Calypso guidelines for CSS](https://wpcalypso.wordpress.com/devdocs/docs/coding-guidelines/css.md).
+- Use BEM for [class names](https://en.bem.info/methodology/naming-convention/).
+- Prefix all class names.

docs/quality-and-best-practices/naming-conventions.md

@@ -0,0 +1,88 @@
+# Naming Conventions
+
+Table of Contents:
+
+- [PHP](#php)
+    - [`/src`](#src)
+    - [`/includes`](#includes)
+- [JS](#js)
+- [CSS and SASS](#css-and-sass)
+
+## PHP
+
+WooCommerce core generally follows [WordPress PHP naming conventions](https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/#naming-conventions). 
+
+There are some additional conventions that apply, depending on the location of the code.
+
+### `/src`
+
+Classes defined inside `/src` follow the [PSR-4](https://www.php-fig.org/psr/psr-4/) standard. See the [README for `/src`](../../plugins/woocommerce/src/README.md) for more information.
+
+The following conventions apply to this directory:
+
+- No class name prefix is needed, as all classes in this location live within the `Automattic\WooCommerce` namespace.
+- Classes are named using `CamelCase` convention.
+- Functions are named using `snake_case` convention.
+- Class file names should match the class name. They do not need a `class-` prefix.
+- The namespace should match the directory structure.
+- Hooks are prefixed with `woocommerce_`.
+- Hooks are named using `snake_case` convention.
+
+For example, the class defined in `src/Util/StringUtil.php` should be named `StringUtil` and should be in the `Automattic\WooCommerce\Util` namespace.  
+
+### `/includes`
+
+The `/includes` directory contains legacy code that does not follow the PSR-4 standard. See the [README for `/includes`](../../plugins/woocommerce/includes/README.md) for more information.
+
+The following conventions apply to this directory:
+
+- Class names are prefixed with `WC_`.
+- Classes are named using `Upper_Snake_Case` convention.
+- Functions are prefixed with `wc_`.
+- Functions are named using `snake_case` convention.
+- Hooks are prefixed with `woocommerce_`.
+- Hooks are named using `snake_case` convention.
+
+Class name examples:
+
+- `WC_Cache_Helper`
+- `WC_Cart`
+
+Function name examples:
+
+- `wc_get_product()`
+- `wc_is_active_theme()`
+
+Hook name examples (actions or filters):
+
+- `woocommerce_after_checkout_validation`
+- `woocommerce_get_formatted_order_total`
+
+## JS
+
+WooCommerce core follows [WordPress JS naming conventions](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/#naming-conventions).
+
+As with PHP, function, class, and hook names should be prefixed, but the convention for JS is slightly different.
+
+- Global class names are prefixed with `WC`. Class names exported from modules are not prefixed.
+- Classes are named using `UpperCamelCase` convention.
+- Global function names are prefixed with `wc`. Function names exported from modules are not prefixed.
+- Functions are named using `camelCase` convention.
+- Hooks names are prefixed with `woocommerce`.
+- Hooks are named using `camelCase` convention.
+
+Global class name example:
+
+- `WCOrdersTable`
+
+Global function name example:
+
+- `wcSettings()`
+
+Hook name example (actions or filters):
+
+- `woocommerceTracksEventProperties`
+
+## CSS and SASS
+
+See [CSS/Sass Naming Conventions](./css-sass-naming-conventions.md).

plugins/woocommerce/changelog/add-doc-naming-conventions

@@ -0,0 +1,4 @@
+Significance: minor
+Type: dev
+
+Migrate naming conventions documentation.