20 Angular Quality Guidelines

• John Vandivier

Question to me: If you were going to conduct a peer review or put together a coding guide for well written angular code, what are some of the things you’d be looking for?

Answer:

  1. Use pull requests for peer review. Prefer major providers like GitHub or Bitbucket. Use a process like Git Flow. Attribute all pull requests to a requirement documented using a requirement ticketing system like Jira or GitHub issues. Ensure the business signs off on each release.
  2. Automation-friendly rules. Use automated testing, prettier, tslint, and similar tools to ensure consistent quality with speed. Pull requests should automatically try to build the codebase, and broken builds should not be mergeable to dev. Dev should never be broken. Use a commit linter.
  3. Use semantic versioning and automate your release notes.
  4. Living rules which are intelligently defaulted but always open to change. Quality guidelines are for the benefit of the team, and the team should always be free to override any rule. Prefer teams of 3 or more developers with peer review or rule changes requiring two approvals in addition to the person who proposed the pull request or rule change.
  5. Build regularly off of dev, and dev should never have a broken build.
  6. Use feature flags to hide WIP features in production and facilitate A/B testing.
  7. Try to adopt evidence-based rules. Showing a rule decreases the defects per sprint, increases velocity, or improves user analytics are examples of the kind of evidence I'm talking about.
  8. Aggressively and redundantly log informative client and server errors. Build monitoring for this stuff.
  9. Every feature should be tested with at least one end to end test. I like to include screenshot testing using Cypress with my end to end tests. 75% line coverage is a good high-quality starter watermark. Don't be afraid to drop to 10% or up to 100% depending on team risk tolerance or another good justification.
  10. Make sure files and functions are uniquely named across the whole project. Variables should be uniquely named at least within the file, and their data type should be intuitive based on their name. Don't use ambiguous named like value or data.
  11. Use a generic wrapper for $http to allow for generic error handling, instead of calling $http directly.
  12. Storybook is a great tool which can allow developers to aggressively commit code which is released only to Storybook and not into production code. Storybook can be shared with designers and product folks to allow better iteration and review without production risk.
  13. Generate components and services using the angular command line tool. Create a module for every distinct route and lazily load them using a routing module. I like to use --flat=false so I get a folder which can be dragged and dropped from one angular app into another. Create a CoreModule which is a top-level module that holds any services which will be used in all routes of the application. An AuthService might be an example.
  14. Alternatively, consider the atomic design folder structure used by the ngx-admin here. You don't need the @ characters in the folder names. Make sure your team is bought in to this approach as it's an alternate to the official style guide approach.
  15. Go over the official style guide with your team and double check which rules you will adopt and which you will ignore. Go ahead and adopt them if you don't have a justification to deviate.
  16. Respect the ecosystem network effect. This means, for example, prefer Bootstrap 4 over CSS Grid at the time of writing. Even though grid is arguably better tech, no one is using it. You should be using a grid system. You will also need a state manager, but it can be a simple Angular service if you prefer that over something like ngrx. Consider using component libraries like Angular Material.
  17. Global styles are terrible, but prefer them over ViewEncapsulation: none which can have unexpected side effects mid-session for a user. Shadow DOM is better than globals, but make sure your browser support requirements allow it. Specifically, that would depend on whether you need IE support.
  18. Each of these little tricks may or may not apply for your project, but talk to your team about using these cool things:
    1. Service workers and web workers
    2. Angular universal
    3. Prerendering / static build
    4. PWA support with an app shell.
  19. In many cases it will make sense to have a mock server for development time. I like to set up a full-blown Express mock server which can respond with built static resources and mock responses instead of the usual proxy approach which is limited. If you end up having a UI project, an Express server, Cypress, and Storybook, consider using a monorepo pattern. A real express server is also more extensible from a mock server into a run-time server or middleware layer.
  20. Prefer scss over css, less, or other options. Css-in-javascript is cool but you should really be thinking about tsx at that point. Tsx is super cool but it's not standard for Angular at this time. At this point in time I recommend you just stick with Angular CLI options like scss. If you really want tsx today you should really be asking if you want Angular at all over React. While it's technically possible, I strongly recommend you do not use React inside of Angular these days.