Ver código fonte

Merge branch 'stable'

Piotrek Koszuliński 5 anos atrás
pai
commit
0bb2140aca
1 arquivos alterados com 203 adições e 1 exclusões
  1. 203 1
      docs/framework/guides/contributing/code-style.md

+ 203 - 1
docs/framework/guides/contributing/code-style.md

@@ -409,7 +409,8 @@ Properties accessibility:
 For instance, a protected property is accessible from its own class in which it was defined, its whole package and from its subclasses (even if not in the same package).
 
 <info-box>
-	Protected properties/methods are often used for testability. Since tests are located in the same package as the code,
+	Protected properties/methods are often used for testability. Since tests are located in the same package as the code they can access these properties.
+</info-box>
 
 ## Getters
 
@@ -471,3 +472,204 @@ There are some special rules for tests.
 * Every test should clean after itself, including destroying all editors and removing all elements that have been added.
 * Avoid using real timeouts. Use [fake timers](https://sinonjs.org/releases/v9.0.1/fake-timers/) instead **when possible**. Timeouts make test really slow.
 * However, thinking about slow – do not overoptimize (especially that performance is not a priority in tests). In most cases it is completely fine (and hence recommended) to create a separate editor for every `it()`.
+
+## Naming
+
+### JavaScript code names
+
+Variable, functions, namespaces, parameters and all undocumented cases must be named in [lowerCamelCase](http://en.wikipedia.org/wiki/CamelCase):
+
+```js
+let a;
+let myLongNamedVariable = true;
+
+function foo() {}
+
+function longNamedFunction( example, longNamedParameter ) {}
+```
+
+Classes must be named in [UpperCamelCase](http://en.wikipedia.org/wiki/CamelCase):
+
+```js
+class MyClass() {}
+
+const a = new MyClass();
+```
+
+Mixins must be named in [UpperCamelCase](http://en.wikipedia.org/wiki/CamelCase), postfixed with "Mixin":
+
+```js
+const SomeMixin = {
+	method1: ...,
+	method2: ...
+};
+```
+
+Global namespacing variables must be named in [ALLCAPS](http://en.wikipedia.org/wiki/All_caps):
+
+```js
+const CKEDITOR_TRANSLATIONS = {};
+```
+
+#### Private properties and methods
+
+Private properties and methods are **prefixed with an underscore**:
+
+```js
+CKEDITOR._counter;
+something._doInternalTask();
+```
+
+#### Methods and functions
+
+Methods and functions are **almost always** verbs/actions:
+
+```js
+// Good
+execute();
+this.getNextNumber()
+
+// Bad
+this.editable();
+this.status();
+```
+
+#### Properties and variables
+
+Properties and variables are **almost always** nouns:
+
+```js
+const editor = this.editor;
+this.name;
+this.editable;
+```
+
+**Boolean properties and variables** are **always** prefixed by an auxiliary verb:
+
+```js
+this.isDirty;
+this.hasChildren;
+this.canObserve;
+this.mustRefresh;
+```
+
+### Shortcuts
+
+For local variables **commonly accepted short versions** for long names are fine:
+
+```js
+const attr, doc, el, fn, deps, err, id, args, uid, evt, env;
+```
+
+The following are **the only short versions accepted for property names**:
+
+```js
+this.lang;
+this.config;
+this.id;
+this.env;
+```
+
+### Acronyms and proper names
+
+Acronyms and, partially, proper names are naturally written in uppercase. This may stand against code style rules described above – especially when there is a need to include acronym or proper name in variable or class name. In such case, one should follow these rules:
+
+* acronyms:
+ * all lowercase if at the beginning of the variable name: `let domError`
+ * default camel case at the beginning of the class name: `class DomError`
+ * default camel case inside variable / class name: `function getDomError()`
+* proper names:
+ * all lowercase if at the beginning of the variable: `let ckeditorError`
+ * original case if at the beginning of the class name: `class CKEditorError`
+ * original case inside variable / class name: `function getCKEditorError()`
+
+However, two letter acronyms and proper names (if originally written uppercase) should be uppercase. So e.g. `getUI` (not `getUi`).
+
+<info-box>
+	Two most frequently used acronyms which cause problems:
+
+	* **DOM** – it should be e.g. `getDomNode()`,
+	* **HTML** – it should be e.g. `toHtml()`.
+</info-box>
+
+### CSS classes
+
+CSS class naming pattern is based on [BEM](https://en.bem.info/) methodology and code-style. All names are in lowercase with optional dash (`-`) between the words.
+
+Top–level building **blocks** begin with mandatory `ck-` prefix:
+
+```CSS
+.ck-dialog
+.ck-toolbar
+.ck-dropdown-menu
+```
+
+**Elements** belonging to the block namespace are delimited by double underscore (`__`):
+
+```CSS
+.ck-dialog__header
+.ck-toolbar__group
+.ck-dropdown-menu__button-collapser
+```
+
+**Modifiers** are delimited by a single underscore (`_`). Key-value modifiers
+follow `block-or-element_key_value` naming pattern:
+
+```CSS
+/* Block modifier */
+.ck-dialog_hidden
+/* Element modifier */
+.ck-toolbar__group_collapsed
+/* Block modifier as key_value  */
+.ck-dropdown-menu_theme_some-theme
+```
+
+In HTML:
+
+```html
+<div class="ck-reset_all ck-dialog ck-dialog_theme_lark ck-dialog_visible">
+	<div class="ck-dialog__top ck-dialog__top_small">
+		<h1 class="ck-dialog__top-title">Title of the dialog</h1>
+		...
+	</div>
+	...
+</div>
+```
+
+### ID attributes
+
+HTML ID attribute naming pattern follows [CSS Classes](#css-classes) naming guidelines. Each ID must begin with `ck-` prefix and consist of dash–separated (`-`) words in lowercase:
+
+```html
+<div id="ck">...</div>
+<div id="ck-unique-div">...</div>
+<div id="ck-a-very-long-unique-identifier">...</div>
+```
+
+### File names
+
+File and directory names must follow a standard that make their syntax easy to predict:
+
+* All lower-cased.
+* Only alphanumeric characters are accepted.
+* Words are separated by dashes (`-`) ([kebab-case](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles)).
+	* Code entities are considered single words, so the `DataProcessor` class is defined in the `dataprocessor.js` file.
+	* However, a test file covering for "mutations in multi-root editors": `mutations-in-multi-root-editors.js`.
+* HTML files have the `.html` extension.
+
+#### Examples
+
+* `ckeditor.js`
+* `tools.js`
+* `editor.js`
+* `dataprocessor.js`
+* `build-all.js` and `build-min.js`
+* `test-core-style-system.html`
+
+#### Standard files
+
+Widely used standard files do not obey the above rules:
+
+* `README.md`, `LICENSE.md`, `CONTRIBUTING.md`, `CHANGES.md`
+* `.gitignore` and all standard "dot-files"
+* `node_modules`