Skip to content

CodingGuidelines

Jump to bottom
ACatThatPrograms edited this page Nov 4, 2022 · 2 revisions

Overview

This is an overview of common standards to use across any of AliceNet’s JavaScript / TypeScript code bases. Any concerns or petitions for change to these standards should be brought up to all developers using these guidelines and adjusted at the final discretion of their respective leads.

Code Formatting

Please install and use VS Code’s prettier package for formatting, optionally prettier is included as a pre-commit hook in all of alicenet's libraries. A prettier configuration will be included in all of the JS/TS repositories, if it is not please include the default which can be found here.

Recommended VSCode Extensions

ES7+ React/Redux/React-Native snippets

GitLens

Path Intellisense

React PropTypes Intellisense

Default Component Frameworks / Libraries

These are the default component frameworks to use unless a project demands differently:

Material UI is used as the baseline component library*
ethers.js is used for all web3 functionality and BigNumber uses. (ethers.BigNumber)

*Please note that we have a middle-man library for handling all MUI themeing. Themes can be found in this library and should be imported from it. As the design system is completed and more applications are developed it is planned to abstract common ocurring components to this library and export them here instead.

React Codebase Organization

If using the /ui-boilerplate as generally required when creating new UI applications, most of these guidelines should be in place. They are provided here for reference for creating more custom application that stray too far from the boilerplate.

File & Folder Hierarchy

  • Application mount must be contained in index.js where it is mounted to the DOM.

  • Application root must be contained in App.js where Routing/Switching should take place

  • Root level pages must be be components placed into a ‘pages' folder with an index.js containing all exports relative to that component hierarchy. If sub-level pages exist this schema should continue.

  • Parent-relative components must be isolated to their parent page folder if not in the Component itself. The exception is: If a component is used in multiple locations throughout the application they should be moved to the next relative parent that covers its scope. If they will are generic and can be used widespread the component may be placed within the generic /components folder.

  • When developing components, unless it is clearly generic, opt to keep components within their context and scope until it is clear the component will be used in other locations.

  • Always test for intellisense usage when developing libraries -- Prioritize developer readability

Casing Guidelines

  • /page/<folder> Where <folder> is a collection of components surrounding a page must be camelCase

  • Filenames of components and classes must be PascalCase

  • Root folders and non-component related folder names must be lowercase

Naming and ES5/ES6 Module Guidelines

  • Opt for ES6 modules where possible.

  • React projects must be setup with absolute imports via jsconfig.json do not use relative imports as they can quickly be difficult to read in heavily nested hierarchies.

  • Most exports should be named exports, not defaults. The exception is: default exports for external libraries developed.

  • Folders with multiple files should have an index.js for named exports

Folders directly related to multipart components should be capitalized (See ComplexGenericComponent for an example below)

Documentation

When writing code please always use JSDoc syntax to document your functions, not only will this provide context to other developers it will allow us to quickly generate specific documentation and provide intellisense to most IDEs without the use of Typescript.

Inline comments are also encouraged in addition to JSDoc if you are doing anything that is not common, such as complex state handling,math, or smart contract related functionality

Custom CSS

Custom CSS should be very rare when using the design system.

However, if needed please use:

  • A root /style folder for generic scss styling that is imported at the root index.js
  • SCSS Modules w sass for the most compact styling

If the custom CSS is modular and can be abstracted it can be placed into a respectively named folder within /style , this should generally be a last resort as generic styles are most likely handled by MaterialUI and component specific styling will be isolated to an scss module and more favorable to the sx prop provided by Material design.

See the below hierarchy for examples

File Hierarchy Example

src/
    components/
        index.js // exports all components in /components directory
        ButtonUsedMultiplePlaces.jsx
        ButtonUsedMultiplePlaces.module.scss
        InputUsedMultiplePlaces.jsx
        InputUsedMultiplePLaces.module.scss
        ComplexGenericComponent1/
        MainComponentPart.jsx
        SubComponentPart.jsx
        index.js // exports MainComponentPart component
    pages/
        home/
            index.js // Should only export Home.jsx
            Home.jsx
            HomeSplashButton.jsx // If needed elsewhere, abstract upwards
        about/
            index.js // Only exports about.jsx component
            about.jsx
            about.module.scss // OPTIONAL: Contains about scss
            CustomAboutButton.jsx // Is not exported by index.js -- Is used in lower scope
            aboutCompany/ // Subpage-1 -- Note lowerCamel
                index.js // Only exports AboutCompany.jsx
                AboutCompany.jsx // Uses CustomAboutButton and AboutCompanyMenu.jsx 
                AboutCompanyMenu.jsx
                AboutCompanyMenu.module.scss
            aboutTeam/
                index.js // Only exports AboutTeam.jsx
                AboutTeam.jsx // Uses CustomAboutButton
                AboutTeamMenu.jsx
            ...{OtherPages}
    style/ ( This folder shoul generally not be needed )
      index.scss // Should import all generic scss files here 
      buttons/
        buttons.scss
      colors/
        colors.scss
      typography/
        typography.scss
      {otherThemeingCategories}/ 
        {...}.scss
    App.js // Project Root Entry
Clone this wiki locally