Evergreen Angular Development Best Practices

Work in progress. Loose collection of practices to review with developers so we can agree on UI developer guidelines.

• Run 'ng build --prod' before committing.
  • This ensures the templates also compile successfully.
• Run 'ng lint' before committing.
  • This does more than check style, it also warns when an import pulls in too much code, among other things.
• Make sure that 'ng extract-i18n' runs before committing (some i18n syntax errors are not caught by ng build)
• use camelCase variables when possible for consistency. (Note fields on IDL objects don't apply).
• Use 2-space indentation in HTML files
• Use 4-space indentation in Typescript and CSS files.
• Avoid column widths in code that extend well beyond 80-100 characters
• Avoid subscribing to Observables within other subscriptions (nested subscriptions). Instead, you should should use pipeable rxjs operators like switchMap, mergeMap, filter, map, and tap. Some of these tslint rules can be helpful for catching nested subscriptions and other RxJS issues.

• Design for screen width of 1350 pixels.
  • This is somewhat arbitrary, but seems to cover most laptops and smaller (non-mobile) screens without being too limiting.
  • Browser dev tools can show the width of the current browser window.
• Use Bootstrap utility classes when possible instead of writing custom CSS.
  • https://getbootstrap.com/docs/4.2/utilities/
  • These are especially useful for margins and padding.
• Use console.debug() for debugging. Use console.log() sparingly. Excessive logging can impact UI speed.
• Make resources deep-linkable where possible (/eg2/path/to/thing/id)
• Give form inputs ID values with linked i18n labels
  • <label for="patron-name" i18n>Name</label><input id="patron-name" …/>
  • Beware repeatable components have unique form input IDs (extend id with incrementor, random(), etc.)
• Give buttons meaningful title or aria-label attributes
• Give images meaningful alt attributes (alt="" is okay for decorative or redundant images; see the W3C decision tree for alt text)
• Test keyboard navigation with tab, shift+tab, arrow keys, and other keys as appropriate. Make sure that all buttons, links, and other interactive elements are focusable.
  • The WAI-Aria Authoring Practices may help you determine the appropriate keyboard interactions for more complex widgets
  • Don't add Bootstrap's "btn" class to unfocusable elements, like <span>s, <label>s, or <a>s that don't also have a "href" attribute. Use a tag that is already focusable instead, like <button> or <a> with a "href" attribute.
• Make sure that your screens have an <eg-staff-banner> at the top to let users know where they are.

• Files named *.spec.ts are automatically treated as unit test files.
• Unit test files should live in the same directory as the code they are testing.
  • e.g. idl.service.ts and idl.spec.ts are in the same directory.
• See Open-ILS/src/eg2/src/app/core/*.spec.ts files unit test examples of core services.
• The highest priority for unit test implementation are shared *.service.ts files, followed by shared components, since changes to these files have the broadest impact.