Current styleguide conventions with modern JS (elastic#8929)

Backports PR elastic#7435

**Commit 1:**
Current styleguide conventions with modern JS

The existing styleguide was in great need of a rewrite as it did not
reflect the conventions we're using in the codebase or even the best
practices that we follow. In some cases, the guidance it provided was
outright contrary to our current practices.

* Original sha: 13e501b
* Authored by Court Ewing <[email protected]> on 2016-06-12T14:03:13Z

Former-commit-id: e967153

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.