Skip to content

CODE_CONVENTIONS.md

Latest commit

 

History

History
57 lines (35 loc) · 4.55 KB

CODE_CONVENTIONS.md

File metadata and controls

57 lines (35 loc) · 4.55 KB
Raw

DSpace Angular Code Conventions

DSpace has established coding conventions or best practices that all contributions must follow in order to be accepted.

These code conventions describe the best practices for design and implementation of DSpace code, helping ensure that all DSpace components have a consistent layout and follow the essential Web Content Accessibility Guidelines (WCAG). The best practices for formatting your code are defined in our separate Code Style Guidelines.

For additional guidelines, see the wiki documentation for User Interface Design Principles & Accessibility.

  1. Enforcement of Guidelines
  2. Angular Guidelines
    1. Templates in Base Theme should only use default Bootstrap styling
    2. Required Bootstrap Components must use ng-bootstrap library
    3. Document methods and classes using TypeDoc
    4. Align with DSpace's User Interface Design Guidelines
  3. Accessibility Guidelines
    1. Align with WCAG (Web Content Accessibility Guidelines) AA criteria
    2. Align with DSpace's User Interface Accessibility Guidelines

Enforcement of Guidelines

Enforcement of these code conventions is handled in two ways:

  • Some guidelines are enforced strictly via static code tools such as ESLint. Where possible, we prefer to automate enforcement.
  • All guidelines are enforced during code review by the assigned reviewers.

Angular Guidelines

Templates in Base Theme should only use default Bootstrap styling

All templates in the Base Theme (/src/app directories) should only use default Bootstrap styling. Documentation at: https://getbootstrap.com/docs/4.6/getting-started/introduction/

Required Bootstrap Components must use ng-bootstrap library

When Bootstrap Components (accordion, dropdown, etc …) are required you MUST use the included ng-bootstrap library. Documentation at: https://ng-bootstrap.github.io/#/components/accordion/examples

Document methods and classes using TypeDoc

Write TypeDoc comments for all new (or modified) public methods and classes, as well as for large or complex private methods.

Align with DSpace's User Interface Design Guidelines

In order to ensure consistent layout and behavior on all pages, please refer to the User Interface Design Guidelines. This documentation provides more details regarding User Interface layout/design and the elements (or components) used by the DSpace User Interface.

Accessibility Guidelines

Align with WCAG (Web Content Accessibility Guidelines) AA criteria

The DSpace User Interface strives to align with WCAG AA criteria. Some AAA criteria may also be supported. For more information see Accessibility documentation.

The use of the Bootstrap framework can help in achieving some WCAG goals such as ‘Visual Presentation’ (AAA), 'Parsing' (A), ‘Orientation’ (AA), ‘Reflow’ (AA) and ‘Text Spacing’ (AA). See the Bootstrap chapter "Accessibility" for an explanation of WCAG and where to find additional information.

Align with DSpace's User Interface Accessibility Guidelines

Refer to the User Interface Accessibility Guidelines for more detailed recommendations regarding HTML structure, ARIA labelling and more.