Coding Style

Conventions

JavaScript has many code style guides. For the SKA Projects we have settled on the AirBnB JavaScript Style Guide.

As a developer it is worth familiarizing yourself with the AirBnB guide above, and some of the background reading that they suggest.

Use of TypeScript

Although it is not the purpose of this guide to dictate the use of TypeScript over JavaScript, there are a number of benefits of doing so, some of which are listed below:

  • Static Typing, which improves code predictability and early error detection

  • Interfaces, allowing the developer to define contracts for Objects

  • Enums, Enabling a developer to declare a set of named constants, which aids in code readability

  • Advanced type checking features

File Suffixes

  • For standard JavaScript, use the suffix .js

  • If JavaScript extension is used, then the suffix should be .jsx

  • Test files should be prefixed .test.{js|jsx}

Note

Most applications are now developed using TypeScript. For standard TypeScript use the suffix .ts. For TypeScript extension, then the suffix should be .tsx

Data and Configuration Files

  • Use proxies and relative paths where possible. Avoid hard coded URLs.

  • Any explicit paths should be derived from a consistent configuration source.

( See example https://facebook.github.io/create-react-app/docs/proxying-api-requests-in-development#configuring-the-proxy-manually )

Logging implementation

Remove all console statements when done. Production code should not contain any console statements.

Accessibility

The components provided in the ska-gui-components have properties called ariaTitle & ariaDescription. The contents of these fields are accessed by standard screen-readers and so should always be populated with meaningful content that will be useful to those that use screen readers. Using components outside of the ska-gui-components should make use of aria-label and aria-description respectively.

Ensure that components and pages make use of the standard SKAO theme as this has been checked and verified to be fully accessible to users across a number of accessibility variations.

Below is an example of using these as part of a standard SKA Button component. Also emphasized is an example of using the testId, which is outlined in the next section

<Button
    ariaDescription="Button that will add a record to the list when clicked"
    ariaText="Add Button"
    color={ButtonColorTypes.Secondary}
    disabled={!enabled()}
    icon={getIcon()}
    label={t('button.add')}
    testId="addButton"
    onClick={buttonClicked}
    variant={ButtonVariantTypes.Contained}
  />

Testing

The components provided in the ska-components-libraries have a property called testId. A unique value should be assigned to this property to ensure that identification of the component during testing is a simple process.

In the example above the testId is emphasized. An example of the use of this as part of testing is shown on the testing page.