Angular 2 Guidelines

We've recently released our Angular 2 Guidelines. As a result, I'd like to take a moment to explain why, and how, they were developed.

Getting started with Angular 2

When starting a project, developers very often have to decide how to structure and write their applications. This first step is even more important when working on large projects, with a large team. Decisions that work just fine when the application is small or even medium-sized tend to fall apart very quickly under the strain of a large, complex and ever-changing body of code. To make matters worse, these same decisions form the foundation of your application and become significantly more difficult to change as the application grows. Teams undertaking a new project must then lean on their previous experiences to ensure the project succeeds down the line.

Style guides help with this process by codifying best practices – which are typically inherited through lessons learned from prior attempts at building the same kind of large applications. While Angular 2 is still young and there are fewer lessons to draw upon, afew have already materialized. Our intent isn't to simply add to their number. Where they presented good ideas, we shamelessly "borrowed" them. You are encouraged to give them a read. Our guidelines, however, aim to go further.

The demands of large-scale JavaScript applications require us to make many more decisions at the onset and those choices have a material impact on how we choose to write Angular 2 code. As such, the guidelines are very much less about how we write Angular but how we write applications using Angular. The distinction is subtle but it makes the difference.

The demands of large-scale JavaScript applications

Building large JavaScript application where data changes over time is challenging. Ensuring that such applications are reliable and function predictably is even more so. To address these challenges, we need an effective architecture for the applications we build. Our Angular 2 Guidelines serve more than just as a style guide. The guidelines cover our chosen architectural patterns and outlines their impact on our Angular 2 writing style.

The old saying that change is the only constant seems eminently applicable to software development. In the general case, then, we strive for codebases where the developer can be confident making changes to the application. This requires that those changes be predictable and that the program be easy to reason about. In that pursuit, we've reached for familiar and battle-tested constraints. In the small, we prefer a functional style where our abstractions are built from small functions operating over immutable data. In the large, we leverage Redux for state management and pair it with a large collection of small state-less view components in order to display our UIs. Between them are a few container components that provides behaviour and data from Redux to the view components they contain.

In a broad sense, the guidelines are about a little more than how best to approach writing a Redux application with Angular 2. They promote writing your application in plain ol' JavaScript and using Redux and Angular 2 to render your interfaces. They further promote writing the plain part as a collection of small, functional and well-tested ES6 modules. The heft of our application logic is then composed of many of these small and functional modules, being used by many small and pure Redux reducers to determine the state that many small state-less view components will display. In our view, the old trope stands: the best way to build large applications is to not build large applications.

Open-sourcing how we think

It's worth explicitly stating that the Angular 2 Guidelines are a living document and a work in progress. They're informed by our experiences thus far and the practices that have worked for us across a varied range of Angular 2 projects at Rangle.io. They may very well change as we learn more. While the guidelines are opinionated, they are first and foremost pragmatic.

We've released them primarily to share our thinking with the community. We not only welcome but encourage questions and discussions. If you follow our guidelines and they fail you, we'd love to hear about it. Any discussion of best practices and style risks being derailed by minor preferences based on aesthetics or simply familiarity. To prevent this requires understanding intent. While the how is important, we hope this post gave you an idea of why we propose doing things the way we do.