Update README.md (angular-ui#33)

Nhan To-Doan · ProLoser · commit 84958aa6ebc0 · 2016-06-30T13:31:15.000-07:00
Improve formatting.
diff --git a/README.md b/README.md
@@ -4,17 +4,14 @@ Scalable architecture in AngularJS
 [Resources](Resources.md)
 -------------
 
-
 Intro
 -------------
-
 Originally forked from ProLoser/AngularJS-ORM
 
 The project demonstrates ways to **leverage ui-router to the greatest of it's abilities**, how to **keep your controllers down to 1 line of code**, how to **organize your services** in a completely simplified manner, and how to **leverage resolves** like a god. Keeping your application down to a **tiny handful of directives**. Avoid the nightmare of lifecycle, transition, and session/stateful bugs. How to **keep your `$scope` clean and tidy**. It doesn't require using `controller as` and it **doesn't turn everything into directives**. Write your code to be **angular-agnostic**. Use the router to **manage state, sessions and collections** allowing you to avoid the problems addressed with complicated flux architectures. Sharing references means **no more watchers and subscribers** strewn across your app.
 
 **_WIP: Please help clean up this repo!_**
 
-
 The StyleGuide
 -------------
 
@@ -25,8 +22,8 @@ In today's code, it's sensible keep modules together and small. HTML, JS and CSS
 This is a practice that is becoming predominant and actually screws up a lot of the benefits of `controllerAs` syntax. Instead of namespacing and bundling controller logic, the only benefit you gain is the little `.` dot notation in `ng-model`. The name `vm` does not tell you where the logic came from or what it has to do with, and does not allow you to work with multiple bundles of logic at the same time. As such, it should be completely avoided. 
 
 #### _[DISPUTED]_ If you can't open-source your directives, they usually shouldn't exist
-A lot of people will create what I refer to as 'one-off' directives. These usually should just be sub-states.
-If you create directives specific to your business logic, and aren't focused on purely UI visual implementation (regardless of data, application, etc) then you are too tightly coupling your business logic to your view. You are making it more difficult to quickly refactor your view or view structure. You have to track down where business logic is being executed or modified in multiple places. You start keeping track of data state and lifecycle and implementing things like events and streams because your view lifecycle isn't consistent with your data lifecycle.  
+A lot of people will create what I refer to as 'one-off' directives. These usually should just be sub-states. If you create directives specific to your business logic, and aren't focused on purely UI visual implementation (regardless of data, application, etc) then you are too tightly coupling your business logic to your view. You are making it more difficult to quickly refactor your view or view structure. You have to track down where business logic is being executed or modified in multiple places. You start keeping track of data state and lifecycle and implementing things like events and streams because your view lifecycle isn't consistent with your data lifecycle.
+
 Instead, 0 business logic in views. Rendering logic in views only. Publicly, reusable, agnostic, unopinionated, highly versatile/reusable view logic.
 
 #### Don't do routing redirects inside services/factories
@@ -49,18 +46,11 @@ Apps that don't let you access their content without being logged in don't have
 #### Don't use `controllerAs` in routes. Use it in directives only.
 _pasted from slack_
 
-Controller instances are not shareable.  
-Meaning if you put logic into a controller (`this.doSomething()`) although you can reuse the logic elsewhere, you can’t reuse the instance.
-`controllerAs` syntax fixes a few issues, but it misleads people into thinking it’s okay to bloat controllers, which it isn’t (except for directives).
-Your stateful logic  shouldn’t be in the controller, it should be in something stateful that can be shared
-so instead put most of your `this.doSomething()` into a factory, preferrably in a `class` or `object instance`.
-Then you can share it across multiple controllers, not just the logic, but the **highly stateful data**:  
-`resolve: { person: function(Person) { return new Person() } }`
+Controller instances are not shareable.
+
+Meaning if you put logic into a controller (`this.doSomething()`) although you can reuse the logic elsewhere, you can’t reuse the instance. `controllerAs` syntax fixes a few issues, but it misleads people into thinking it’s okay to bloat controllers, which it isn’t (except for directives). Your stateful logic shouldn’t be in the controller, it should be in something stateful that can be shared so instead put most of your `this.doSomething()` into a factory, preferrably in a `class` or `object instance`. Then you can share it across multiple controllers, not just the logic, but the **highly stateful data**: `resolve: { person: function(Person) { return new Person() } }`
 
-You inject `person` into multiple controllers and they all share the same data, and update in sync.
-So instead of doing `this.doSomething()` in your controller, and keeping track of info about how a `Person` works inside a controller (_which is reusable, but **not shareable**_) you should keep it inside your factories, which are even FURTHER abstracted from the view/angular-centric mindset, but are also instantiatable and manageable.
-I can control more concretely when a person is created, destroyed, updated, who has access to it, how it gets reused, etc.
-Angular no longer handles the lifecycle of the data, i do.
+You inject `person` into multiple controllers and they all share the same data, and update in sync. So instead of doing `this.doSomething()` in your controller, and keeping track of info about how a `Person` works inside a controller (_which is reusable, but **not shareable**_) you should keep it inside your factories, which are even FURTHER abstracted from the view/angular-centric mindset, but are also instantiatable and manageable. I can control more concretely when a person is created, destroyed, updated, who has access to it, how it gets reused, etc. Angular no longer handles the lifecycle of the data, i do.
 
 Controllers are generally 2-10 lines of code so my controller does nothing more than putting my business logic onto the view and occasionally wrapping business logic with view logic and / or route logic:  
 ```
@@ -74,34 +64,17 @@ $scope.save = function(){
 });
 ```
 
-Now lets say you STILL wanted to use `controllerAs` yet still keep things organized the way I described.
-You CAN, except your bindings look like this: `<input ng-model=“personCtrl.person.name”>`
-instead of just `<input ng-model=“person.name”>`.
-That is fairly trivial, but there is another big annoyance I have with it.
-**Your view is no longer reusable with different controllers**.
+Now lets say you STILL wanted to use `controllerAs` yet still keep things organized the way I described. You CAN, except your bindings look like this: `<input ng-model=“personCtrl.person.name”>` instead of just `<input ng-model=“person.name”>`. That is fairly trivial, but there is another big annoyance I have with it. **Your view is no longer reusable with different controllers**.
 
-Lets say i want to use the same view with a create vs edit controller.
-My view bindings have to be `<input ng-model=“createCtrl.person.name”>` or `<input ng-model=“updateCtrl.person.name”>`
-or lets just say you call the controller `person` or `personCtrl`.
-You could have a `personEditCtrl` inside of a `personViewCtrl`
-so who gets which namespace?
+Lets say i want to use the same view with a create vs edit controller. My view bindings have to be `<input ng-model=“createCtrl.person.name”>` or `<input ng-model=“updateCtrl.person.name”>` or lets just say you call the controller `person` or `personCtrl`. You could have a `personEditCtrl` inside of a `personViewCtrl` so who gets which namespace?
 
 When you start to build big apps and deal with these design questions, I find `controllerAs` is **NOT** the answer.  
-I like having brittle scope bindings, for instance you may have cringed when i did `$scope.loading = true` because if you put a `ng-click=“loading = false”` inside of an `ng-if` it won’t work.
-Except I _want_ to keep my view-state flags shallow, simple, clean, and I don’t want the view to update them.
-I like having 2 controllers, both with their own `loading` flags that are not the same variable.
-I prefer not having to namespace all my loading flags by my controller name or variable or state name, and yet my views simply don’t care.
-To them, doing `ng-show=personLoading` is the same as doing `ng-show=personCtrl.loading` and
-my view becomes more brittle and heavily tied to the controller in use.
+I like having brittle scope bindings, for instance you may have cringed when i did `$scope.loading = true` because if you put a `ng-click=“loading = false”` inside of an `ng-if` it won’t work. Except I _want_ to keep my view-state flags shallow, simple, clean, and I don’t want the view to update them. I like having 2 controllers, both with their own `loading` flags that are not the same variable. I prefer not having to namespace all my loading flags by my controller name or variable or state name, and yet my views simply don’t care. To them, doing `ng-show=personLoading` is the same as doing `ng-show=personCtrl.loading` and my view becomes more brittle and heavily tied to the controller in use.
 
 **In directives, it’s a completely different ballgame**  
-Because *directives* are entirely about view logic, and should almost never do business logic. Period.
-The old way of doing directives you put all your shit into a linking function.
-A directive controller is essentially identical to a linking function except it is **reusable by other directives**, a visual-widget's externally visible api.
-If you look at [ui-select](https://github.com/angular-ui/ui-select) i love `controllerAs` because I can give it methods like `uiSelectCtrl.open()`
-and that really is what it’s doing. It’s the controls for my `ui-select` widget.  
-`personCtrl.person.open()` just doesn’t make sense if you read it. The ‘controller’ (guy doing shit to people) isn’t the one with the method, the object itself has methods that work upon itself.
-Doing `personCtrl.open()` is just a sign of bad design, because controllers should be skinny.
+Because *directives* are entirely about view logic, and should almost never do business logic. Period. The old way of doing directives you put all your shit into a linking function. A directive controller is essentially identical to a linking function except it is **reusable by other directives**, a visual-widget's externally visible api. If you look at [ui-select](https://github.com/angular-ui/ui-select) i love `controllerAs` because I can give it methods like `uiSelectCtrl.open()` and that really is what it’s doing. It’s the controls for my `ui-select` widget.
+
+`personCtrl.person.open()` just doesn’t make sense if you read it. The ‘controller’ (guy doing shit to people) isn’t the one with the method, the object itself has methods that work upon itself. Doing `personCtrl.open()` is just a sign of bad design, because controllers should be skinny.
 
 #### Never use scope inheritence across controllers (ui-views)
 This is like using `$rootScope`, it's equivalent to using global variables and relies upon assumptions that variables will exist. It makes controllers (and views) depend on variables that may or may not exist, and makes it difficult for developers to see where these variables came from. If you wish to use a service, resolve or something inside of a route controller or view, you should **always re-inject the dependency and place it on the scope redundantly**. This is single-handedly the key to ensuring that your codebase has a solid contract and that the quality of your code stands up to refactoring. Even if it means placing the same objects onto the same variables in the same place on the scope, do it. Period.
@@ -114,8 +87,6 @@ Example:
 `<div ui-grid ui-grid-sortable ui-grid-paginate>`
 
 #### Use the object to manage _data_ state
-Instead of putting heavy load on _view_ state flags that describe how things should _look_, use grammar that
-describes the verb-like state of the data or action itself. This can then be repurposed in multiple ways in
-in the view as to the visual representation, and is not tied to visual information.
+Instead of putting heavy load on _view_ state flags that describe how things should _look_, use grammar that describes the verb-like state of the data or action itself. This can then be repurposed in multiple ways in the view as to the visual representation, and is not tied to visual information.
 
 Instead of `$scope.showSpinner` or `$scope.loading` use `task.uploading` or `project.saving` which could be rendered as a spinner, form, panel, whatever. The point is the **state flag is agnostic about the visual implementation**.
