[5.x] Current styleguide conventions with modern JS

STYLEGUIDE.md

@@ -1,110 +1,20 @@
-This is a collection of style guides for Kibana projects. The include guides for the following:
+# Kibana Style Guide
+
+This guide applies to all development within the Kibana project and is
+recommended for the development of all Kibana plugins.
 
 - [JavaScript](style_guides/js_style_guide.md)
+- [Angular](style_guides/angular_style_guide.md)
 - [CSS](style_guides/css_style_guide.md)
 - [HTML](style_guides/html_style_guide.md)
 - [API](style_guides/api_style_guide.md)
 
-# Kibana Style Guide
-
-Things listed here are specific to Kibana and likely only apply to this project
-
-## Share common utilities as lodash mixins
-
-When creating a utility function, attach it as a lodash mixin.
-
-Several already exist, and can be found in `src/kibana/utils/_mixins.js`
-
 ## Filenames
 
-All filenames should use `snake_case` and *can* start with an underscore if the module is not intended to be used outside of its containing module.
+All filenames should use `snake_case`.
 
 *Right:*
   - `src/kibana/index_patterns/index_pattern.js`
-  - `src/kibana/index_patterns/_field.js`
 
 *Wrong:*
   - `src/kibana/IndexPatterns/IndexPattern.js`
-  - `src/kibana/IndexPatterns/Field.js`
-
-## Modules
-
-Kibana uses WebPack, which supports many types of module definitions.
-
-### CommonJS Syntax
-
-Module dependencies should be written using CommonJS or ES2015 syntax:
-
-*Right:*
-
-```js
-const _ = require('lodash');
-module.exports = ...;
-```
-
-```js
-import _ from 'lodash';
-export default ...;
-```
-
-*Wrong:*
-
-```js
-define(['lodash'], function (_) {
-  ...
-});
-```
-
-## Angular Usage
-
-Kibana is written in Angular, and uses several utility methods to make using Angular easier.
-
-### Defining modules
-
-Angular modules are defined using a custom require module named `ui/modules`. It is used as follows:
-
-```js
-var app = require('ui/modules').get('app/namespace');
-```
-
-`app` above is a reference to an Angular module, and can be used to define controllers, providers and anything else used in Angular. While you can use this module to create/get any module with ui/modules, we generally use the "kibana" module for everything.
-
-### Private modules
-
-A service called `Private` is available to load any function as an angular module without needing to define it as such. It is used as follows:
-
-```js
-app.controller('myController', function($scope, otherDeps, Private) {
-  var ExternalClass = Private(require('path/to/some/class'));
-  ...
-});
-```
-
-*Use `Private` modules for everything except directives, filters, and controllers.*
-
-### Promises
-
-A more robust version of Angular's `$q` service is available as `Promise`. It can be used in the same way as `$q`, but it comes packaged with several utility methods that provide many of the same useful utilities as Bluebird.
-
-```js
-app.service('CustomService', function(Promise, otherDeps) {
-  new Promise(function (resolve, reject) {
-    ...
-  });
-
-  var promisedFunc = Promise.cast(someFunc);
-
-  return Promise.resolve('value');
-});
-```
-
-### Routes
-
-Angular routes are defined using a custom require module named `routes` that remove much of the required boilerplate.
-
-```js
-require('ui/routes')
-.when('/my/object/route/:id?', {
-  // angular route code goes here
-});
-```

style_guides/angular_style_guide.md

@@ -0,0 +1,65 @@
+# Angular Style Guide
+
+Kibana is written in Angular, and uses several utility methods to make using
+Angular easier.
+
+## Defining modules
+
+Angular modules are defined using a custom require module named `ui/modules`.
+It is used as follows:
+
+```js
+const app = require('ui/modules').get('app/namespace');
+```
+
+`app` above is a reference to an Angular module, and can be used to define
+controllers, providers and anything else used in Angular. While you can use
+this module to create/get any module with ui/modules, we generally use the
+"kibana" module for everything.
+
+## Promises
+
+A more robust version of Angular's `$q` service is available as `Promise`. It
+can be used in the same way as `$q`, but it comes packaged with several utility
+methods that provide many of the same useful utilities as Bluebird.
+
+```js
+app.service('CustomService', (Promise, someFunc) => {
+  new Promise((resolve, reject) => {
+    ...
+  });
+
+  const promisedFunc = Promise.cast(someFunc);
+
+  return Promise.resolve('value');
+});
+```
+
+### Routes
+
+Angular routes are defined using a custom require module named `routes` that
+removes much of the required boilerplate.
+
+```js
+import routes from 'ui/routes';
+
+routes.when('/my/object/route/:id?', {
+  // angular route code goes here
+});
+```
+
+## Private modules
+
+A service called `Private` is available to load any function as an angular
+module without needing to define it as such. It is used as follows:
+
+```js
+import PrivateExternalClass from 'path/to/some/class';
+app.controller('myController', function($scope, otherDeps, Private) {
+  const ExternalClass = Private(PrivateExternalClass);
+  ...
+});
+```
+
+**Note:** Use this sparingly. Whenever possible, your modules should not be
+coupled to the angular application itself.