From b8d91be0120323d63c421c2b10d13918fb458c13 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Mon, 2 Jul 2018 12:45:03 -0400 Subject: [PATCH 1/3] Documentation: Coding Guidelines: Prescribe specific camelCasing behaviors --- docs/reference/coding-guidelines.md | 52 +++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/docs/reference/coding-guidelines.md b/docs/reference/coding-guidelines.md index dabdf0c316affc..db7c8e4ee4283f 100644 --- a/docs/reference/coding-guidelines.md +++ b/docs/reference/coding-guidelines.md @@ -98,6 +98,58 @@ export { } from './internalApi.js'; ``` +### Variable Naming + +Gutenberg inherits [WordPress' naming conventions of camel-casing](https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/#naming-conventions): + +>Variable and function names should be full words, using camel case with a lowercase first letter. This is an area where this standard differs from the WordPress PHP coding standards. +> +>Constructors intended for use with `new` should have a capital first letter (UpperCamelCase). + +However, Gutenberg is more specific about its handling of abbreviations, acronyms, constants, and the ES2015 class construct. + +#### Abbreviations and Acronyms + +[*Abbreviations*](https://en.wikipedia.org/wiki/Abbreviation) must be written as camel case, with an initial capitalized letter followed by lowercase letters. + +[*Acronyms*](https://en.wikipedia.org/wiki/Acronym) must be written with each of its composing letters capitalized. This is intended to reflect that each letter of the acronym is a proper word in its expanded form. + +**Examples:** + +```js +// "Id" is an abbreviation of "Identifier": +const userId = 1; + +// "DOM" is an acronym of "Document Object Model": +const currentDOMDocument = window.document; +``` + +#### Class Definition + +A [`class` definition](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) must use the UpperCamelCase convention, regardless of whether it is intended to be used with `new` construction. + +**Example:** + +```js +class Earth { + static addHuman( human ) { + Earth.humans.push( human ); + } + + static getHumans() { + return Earth.humans; + } +} + +Earth.humans = []; +``` + +#### Constants + +An exception to camel case is made for constant values which are never intended to be reassigned or mutated. Such variables must use the [SCREAMING_SNAKE_CASE convention](https://en.wikipedia.org/wiki/Snake_case). + +In almost all cases, a constant should be defined in the top-most scope of a file. It is important to note that [JavaScript's `const` assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) is conceptually more limited than what is implied here, where a value assigned by `const` in JavaScript can in-fact be mutated, and is only protected against reassignment. A constant as defined in these coding guidelines applies only to values which are expected to never change, and is a strategy for developers to communicate intent moreso than it is a technical restriction. + ## PHP We use From 85315762d41c9939568fd4579e187f5fcd32aef2 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Mon, 9 Jul 2018 08:59:26 -0400 Subject: [PATCH 2/3] Docs: Clarify start-of-variable abbreviation capitalization --- docs/reference/coding-guidelines.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/reference/coding-guidelines.md b/docs/reference/coding-guidelines.md index db7c8e4ee4283f..c28c35ccbd2fdf 100644 --- a/docs/reference/coding-guidelines.md +++ b/docs/reference/coding-guidelines.md @@ -114,6 +114,8 @@ However, Gutenberg is more specific about its handling of abbreviations, acronym [*Acronyms*](https://en.wikipedia.org/wiki/Acronym) must be written with each of its composing letters capitalized. This is intended to reflect that each letter of the acronym is a proper word in its expanded form. +If an abbreviation or an acronym occurs at the start of a variable name, it must be written to respect the camelcase naming rules covering the first letter of a variable or class definition. For variable assignment, this means writing the abbreviation entirely as lowercase. For class definitions, its initial letter should be capitalized. + **Examples:** ```js @@ -122,6 +124,12 @@ const userId = 1; // "DOM" is an acronym of "Document Object Model": const currentDOMDocument = window.document; + +// Acronyms and abbreviations at the start of a variable name are consistent +// with camelcase rules covering the first letter of a variable or class. +const domDocument = window.document; +class DOMDocument {} +class IdCollection {} ``` #### Class Definition From 4263e556fc889206fee5b22d54a1cd910f4e586b Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Mon, 9 Jul 2018 09:01:51 -0400 Subject: [PATCH 3/3] Docs: Clarify components capitalization --- docs/reference/coding-guidelines.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/reference/coding-guidelines.md b/docs/reference/coding-guidelines.md index c28c35ccbd2fdf..ca74c692122930 100644 --- a/docs/reference/coding-guidelines.md +++ b/docs/reference/coding-guidelines.md @@ -152,6 +152,16 @@ class Earth { Earth.humans = []; ``` +All `@wordpress/element` Components, including stateless function components, should be named using Class Definition naming rules, both for consistency and to reflect the fact that a component may need to be transitioned from a function to a class without breaking compatibility. + +**Examples:** + +```js +class MyComponent extends Component {} + +function MyComponent() {} +``` + #### Constants An exception to camel case is made for constant values which are never intended to be reassigned or mutated. Such variables must use the [SCREAMING_SNAKE_CASE convention](https://en.wikipedia.org/wiki/Snake_case).