Why Have Guidelines?
When Rangle.io was smaller, we found it easy to synchronize our approaches and identify best practices simply by gathering in front of a whiteboard when a disagreement arose. As the company grew, it became important to have a more robust approach to ensure that everyone stays on the same page. Since we work primarily on short client engagements, we also wanted to make sure that the code we hand off to our clients reflects a consistent approach. And we also needed to be able to add people to a project quickly without spending precious time on onboarding. The Guidelines were a response to those needs.
Introducing formal guidelines did raise a concern: would it potentially squash the creative spirit inside Rangle.io? We've dealt with this by making the guidelines a collective endeavor. The initial version of the Guidelines was written by myself, as the CTO, to allow for quick progress and to set up the a tone to ensure consistent voice. Since then, however, we have put a lot of effort into ensuring that the guidelines reflect the collective experience of Rangle.io's developers. The more recent revisions of the guidelines include sections contributed by different developers and we have tried to set up a process where everyone has a say.
Developers are expected to follow the guidelines in their current form, but they are also strongly encouraged to speak up when they disagree, by entering issues to the guidelines repository or by submitting pull requests. We use pull requests for all modifications to the guidelines. All such pull requests are reviewed by someone other than the author. More substantial pull requests are kept around for a while to allow everyone to contribute to the discussion. Additionally, major additions or revisions to the guidelines are usually discussed at a lunch-and-learn.
When we started on the guidelines, our initial plan was to produce more of a style guide, dealing with common "style" questions. Some of those things end up eventually being removed from the document and outsourced to tools such as JSHint and JSBeautifier. On the other hand, other sections ended up being expanded based on things that would come up in code reviews.
At the moment the Guidelines have the following sections:
0. Introduction: General principles and philosophy.
1. Defensive Programming: Techniques for making it easier to avoid bugs and to catch them early.
2. Readable Code: Ways to make your code easier to read.
5. Model-View-Controller: Applying the MVC approach, in particular in AngularJS.
6. Code Reuse and Modularity: Techniques for making code more reusable and modular.
7. Testing and Debugging: Approaches for testing and debugging.
8. Security and Privacy: Ensuring security and practices.
9. Teamwork: Working together as a team, in particular using Git.
While we work primarily with AngularJS, we also work with other front-end frameworks, as well as with NodeJS on the backend. For this reason, we have tried to avoid developing a style guide that is narrowly tailored for AngularJS. Instead, we've organized it around general principles and included our AngularJS recommendations as special cases under the more general guidelines. This proved to be a good excersise, as it forced us to think more about the broader principles. I expect that this will also pay off as we move to Angular 2.
A Style Guide for the Guidelines
Our Guidelines take a form of a collection of actionable "commandments." Those usually take a form of a positive recommendation, either hard ("Run linting in CI") or soft ("Consider using a Git pre-commit hook"). Sometimes the take a negative form, again either hard ("Do not trust the client") or soft ("Avoid long promise chains"), though we try to minimize this. When presenting negative guidelines, we try to ensure that the positive alternative is provided.
Each guideline is usually described at multiple levels. The first level is the "commandment" statement itself. The next level is a short explanation, usually a few sentences, that explains what the recommendation is and provides brief rationale. Many guidelines also have a third part: a more detailed explanation that gets into the specifics. This is usually appropriate when the guideline needs concrete examples or where the rationale would benefit from being explained in more depth. Our approach has usually been to keep the guidelines short initially, but to expand the details section if the guideline raises questions or becomes a matter of debate.
Engaging the Community
Over the next few months we'll be writing a series of blog posts highlighting some specific points of our guidelines. We hope that those posts and our released guidelines will help us engage the community in a discussion of best practices.
We released our guidelines on the first day of ng-conf. On the second day, John Papa presented his AngularJS Style Guide. Upon reviewing John's guidelines, we found that we agree on many principles, have minor discrepancies on some, and possibly a strong disagreement in a few cases. When it comes to minor differences, we'll be looking whether we can fix our guidelines to match John's, because we believe that it would be useful to maintain a common practice. For those cases where we disagree, we'll have blog posts explaining why we take our position.