Angularjs style guide adoption - John Papas
As a team we adopted John Papas Angularjs style guide at the end of 2014. The Anguarjs communities understanding of best practices for Angularjs use has come a long way is a short time. I can say now having adopted and used it that John Papas style guide is a good step forward.
We've been developing with Angularjs since 2013 and over that time our Angularjs code base looks quite different style wise. It looks like it was written by many (talented) individuals for various reasons such as our use of best practices evolved. Ideally the codebase should look as if written by one person: easy to learn and understand other peoples code.
So as a team we wanted to write better Angularjs code.
We are also looking ahead to Angular 2.0. There are significant changes in that release and where possible we'd like to write code now that will make it easier to adopt Angular 2.0 in future.
As a team we investigated various angularjs coding standards/style guides such as googles, codeless, todd motos and john papas. All are good, John Papas guide seemed most appropriate to us: it is very detailed, has good feedback in the community and the angular core team, has numerous good rules and has also been written with a view to making Angular 2.0 adoption easier.
To adopt, as a team we reviewed each rule in the style guide and decided to adopt or not. Most were quickly adopted, some required discussion. We spent a number of hours as a team going over the complete set.
I really like the simple idea of separate files for each module definition and also separate files per controller/service. In some cases we did not do that. Yes it means more files, but I think more important is a logical way to easily find controllers/services. It also makes it easy to more easily group many controllers/services under the same module, each just gets the module which is declared once.
Two important gotachas with this approach:
1. we had to modify the karma files list property to include modules files first before unit tests and
2. we had to modify our build code so that the minifier also included modules files first before code that referenced the modules.
A big impact to our codebase will be folder organization. We currently organize by type e.g. /controller or /service, as our codebase has grown we're finding that does not scale well: lots of files, hard to find code you're looking for, not easy to grok, a bit disorganized. John Papas style guide talks about this.
We'd prefer to organize by feature with modules under feature. Common components would be accessible to all features (not "belong" to any one feature). We also need to package code into apps e.g. think admin app vs user and include that in our folder org (as well as build process).
Tied in with this are a number of other rules such as file naming e.g. should you include the word "controller" in the filename for controllers? This is our next step in adopting the style guide.
We are building more directives now than we used to, we see these as components in component based development. Should we go a step further and package them as standalone components? e.g. Bower files? Even though most of our code is internal not for sharing I'd like to experiment some with that since it applies a final rigorous touch.
p.s. is this a syle guide or coding standards?
To me, a style guide is optional whereas coding standards must be followed. Frankly this is a set of coding standards to our team. We want everyone on the team to follow what we all agreed as a team, not optional per developer.
Catch my drift?
We've been developing with Angularjs since 2013 and over that time our Angularjs code base looks quite different style wise. It looks like it was written by many (talented) individuals for various reasons such as our use of best practices evolved. Ideally the codebase should look as if written by one person: easy to learn and understand other peoples code.
So as a team we wanted to write better Angularjs code.
We are also looking ahead to Angular 2.0. There are significant changes in that release and where possible we'd like to write code now that will make it easier to adopt Angular 2.0 in future.
As a team we investigated various angularjs coding standards/style guides such as googles, codeless, todd motos and john papas. All are good, John Papas guide seemed most appropriate to us: it is very detailed, has good feedback in the community and the angular core team, has numerous good rules and has also been written with a view to making Angular 2.0 adoption easier.
To adopt, as a team we reviewed each rule in the style guide and decided to adopt or not. Most were quickly adopted, some required discussion. We spent a number of hours as a team going over the complete set.
I really like the simple idea of separate files for each module definition and also separate files per controller/service. In some cases we did not do that. Yes it means more files, but I think more important is a logical way to easily find controllers/services. It also makes it easy to more easily group many controllers/services under the same module, each just gets the module which is declared once.
Two important gotachas with this approach:
1. we had to modify the karma files list property to include modules files first before unit tests and
2. we had to modify our build code so that the minifier also included modules files first before code that referenced the modules.
A big impact to our codebase will be folder organization. We currently organize by type e.g. /controller or /service, as our codebase has grown we're finding that does not scale well: lots of files, hard to find code you're looking for, not easy to grok, a bit disorganized. John Papas style guide talks about this.
We'd prefer to organize by feature with modules under feature. Common components would be accessible to all features (not "belong" to any one feature). We also need to package code into apps e.g. think admin app vs user and include that in our folder org (as well as build process).
Tied in with this are a number of other rules such as file naming e.g. should you include the word "controller" in the filename for controllers? This is our next step in adopting the style guide.
We are building more directives now than we used to, we see these as components in component based development. Should we go a step further and package them as standalone components? e.g. Bower files? Even though most of our code is internal not for sharing I'd like to experiment some with that since it applies a final rigorous touch.
p.s. is this a syle guide or coding standards?
To me, a style guide is optional whereas coding standards must be followed. Frankly this is a set of coding standards to our team. We want everyone on the team to follow what we all agreed as a team, not optional per developer.
Catch my drift?
Comments
Post a Comment