Skip to main content

Writing good code

Creating and maintaining software libraries is difficult, especially with an open contribution model. We use several tools to help writing better code with consistent naming and formatting.

Supported web frameworks​

The web ecosystem is constantly evolving, new frameworks and platforms appearing every year.

Quartz strategy is to provide standard web components that will work with every current and future web frameworks. Additional support for popular frameworks is provided on a best-effort basis.

Stencil.js for Prism foundations​

Prism foundation packages all implement their components using the Stencil.js library. Stencil generates native web components in a library, as well as framework wrappers (Angular, React, Vue) that improve the developer experience in those frameworks.

With time, the foundation teams have mastered Stencil to optimize the generated libraries, including hydration to support SSR.

Facet libraries​

To keep contribution easy for facet maintainers, we don't enforce using Stencil. You can start contributing components only for the framework that is most used among the projects consuming your facet.

Defining the APIs​

Most component properties are specified upfront by the designer, but you should also double-check the following principles and ask your designer to make changes as necessary:

  • be as close as possible to native web components' APIs
  • be consistent with the the transversal system principles

Then, make sure to follow the naming translation described in the Designer-Developer continuity page.

Checking consistency with the native web components​

Use the MDN documentation as the best reference for checking native web components' API.

Checking consistency with the transversal system principles​

Providing common native APIs​

Principles:

  • Align on the native web components

Other:

  • Prefer false boolean property defaults. These tend to be less verbose in frameworks like React and Vue where only the prop name needs to be used to set its value to true.
  • Rename most option props to something else and change their data types where appropriate. For example, the option prop with a value of "stacked" for the se-form-field element would be better as a stacked boolean prop with a false default value.
  • The color sometime represent color of the button, sometime color of the background. color in se-container should actually be color-background since using background-standard and background-alternative and not the button standard and alternative color.
  • Each component should have no margin to insure that spacing between element is defined from the layout perspective (thanks to classes) and not using configuration.
  • se-list-group and se-list-item don't follow html best practice. It should be possible to have an item inside an item. right now recursive list are hard to create since not following * convention. se-list-item should be more flexible for customization.
  • se-app should not include it's own style or layout classes (flex, color variable...), layout and responsive should be done by an external css library or by a specific component.

:::

Testing​

Code documentation​

Accessibility​

Writing CSS​

Right-to-left (RTL) languages​

Responsiveness​

Tailwind utilities​

Code quality​

We use the following tools to help writing good and consistent code and monitor its quality.

Formatting​

Formatting involves two things:

  • applying formatting rules to your code
  • checking that all files follow the formatting rules

We use the following formatting tools:

Applying formatting rules can be done in two ways:

Checking formatting is part of the linting stage.

Linting​

Linting refers to static code analysis used to flag programming errors, bugs, stylistic errors and suspicious constructs.

We use the following linting tools:

They can be run in different ways:

  • manually running the yarn lint script
  • when the CI detects a Pull Request (or a push to a branch)
  • when you commit, the pre-commit hook runs them on the staged files only.

pre-commit hook​

We use husky to install a pre-commit hook that will use lint-staged to run linting and formatting checks only on the staged files (which is much faster).

We must be cautious with copyright and license material every time we publish source code.

Guidelines​

  • We must ensure that all our assets have an explicit copyright notice of the form: © <YEAR> Schneider Electric.
  • We must ensure that all our assets have an explicit license notice, being LGPL-2.1-only for source code and <ToBeDefined> for creative assets like pictures and icons.
  • We conform to the REUSE standard practices. We benefit from provided tooling and future-proof our effort.

Tooling​

We use the reuse python tool. See the tutorial.

Project-level configuration​

  1. Create a .reuse/dep5 file containing the following boilerplate:

    Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
    Upstream-Name: Quartz documentation website
    Source: https://github.com/quartzds/quartzds.github.io

    Files:
      *.json
      yarn.lock
    Copyright: © 2022 Schneider Electric
    License: LGPL-2.1-only

    Files:
      .yarn/*
    Copyright: (see individual packages)
    License: CC0-1.0

    Adjust these initial rules to make sure creative assets are included (jpg, SVG, etc.)

Use the following commands to automatically inject the proper metadata in your file headers:

  • Single file: reuse addheader --copyright="Schneider Electric" --license=LGPL-2.1-only --copyright-style=spdx-symbol <files>
  • Entire folder: reuse addheader --copyright="Schneider Electric" --license=LGPL-2.1-only --copyright-style=spdx-symbol --skip-unrecognised -r <folder>

Downloading license files​

  1. Automatically download the license files using: reuse download --all
  2. Run reuse lint to review that all the files of the project have valid license metadata
    • Edit the .reuse/dep5 file to add rules for specific cases like generated files (yarn.lock, etc.) or creative assets (jpg

About static assets like images​

Last updated on