What is a style guide? Do AngularJS projects need a style guide, and why? Which are the most popular AngularJS style guides? How would you use a style guide in a team of developers? This article is going to answer all these questions. Before diving into AngularJS style guides, let's look at what a style guide is and why we developers need one.
Why Style Guides
Wikipedia provides a good general definition that can be useful to understand why style guides are important and to get the big picture before diving into AngularJS style guides.
A style guide (or manual of style) is a set of standards for the writing and design of documents, either for general use or for a specific publication, organization, or field. A style guide establishes and enforces style to improve communication. To do that, it ensures consistency within a document and across multiple documents and enforces best practice in usage and in language composition, visual composition, orthography and typography. For academic and technical documents, a guide may also enforce the best practice in ethics (such as authorship, research ethics, and disclosure), pedagogy (such as exposition and clarity), and compliance (technical and regulatory).
Coding style guides enforce the best practice in relation to a particular language and to your organization's needs.
Project Style Guides
There are a number of reasons why JavaScript projects need a style guide. I'm not going to cover all of them in full detail in this article, but they usually expand on the language style guide by covering the following additional topics:
- Modularity: single responsibility, immediately invoked function expressions, module dependencies
- Application structure: architectural patters, folders structure
- Naming conventions: for modules, controllers, configuration and spec files
- Linting: JavaScript code checkers
- Testing: the approach in writing specs
- Comments: to produce documentation
- Startup logic: configuration, startup logic
- Routing: navigation flow, view composition
- Exception Handling: decorators, exception catchers, route errors
- Performance and Security: minification, obfuscation
Existing JavaScript Style Guides
For JavaScript there are a number of general and project-specific style guides out there:
- Google JavaScript Guide
- Mozilla coding style
- Crockford’s code conventions
- Waldron’s Principles of Writing Consistent, Idiomatic JavaScript
- npm’s “funny” coding style
- jQuery’s JavaScript Style Guide
- Airbnb JavaScript style guide
Despite the big names, none of the style guides mentioned above is totally comprehensive. In my opinion, the Airbnb style guide is the most up-to-date and comprehensive, and provides also eslint configuration files with which you can automatically check your code style. The eslint configuration files can be extended, as I did when building my web site.
Why AngularJS Projects Need a Style Guide
AngularJS projects need a style guide pretty much for the same reason all JavaScript projects need a style guide, but there are some Angular-specific items that can be covered.
Let's consider the following AngularJS-specific examples:
-
How to use ng tags. AngularJS ng directives can be used in different ways and have a different syntax, for example preferring data-ng instead of ng when using the ng directive as an HTML attribute, in order to be W3C-compliant. Specifying how to write ng directives in a code style guide helps improving consistency in the HTML files.
-
Different ways to implement components. AngularJS implements web components using custom directives. Custom directives can be based on HTML element names, attributes, class names, as well as comments. A style guide might assure that only one type of directive is used within a project for example.
-
Which architectural pattern to adopt. AngularJS allows for MV* (or MVW) architectural patterns. That leaves the choice to JavaScript developers about whether to implement their application based on MVC or MVVM. Guidelines about what kind of approach has to be used in the project helps in keeping the whole team on the same track.
Continue reading %An Introduction to AngularJS Style Guides%
by Francesco Iovine via SitePoint
