/
โœ…

Coding standards

Table of contents

toc

Naming Conventions

The objective of this document is to help when naming things and make the codebase consistent and easier to read.

Name Rules

๐Ÿฅณ Names should be always be Descriptive & Succinct. ๐ŸŽ‰

๐Ÿ˜‘ Names should not be Obscure or Abbreviated โŒ

File Names

NameConventionExample
Index file`index.(tsjs)`
React component`ComponentName.(tsxts
Test file`ComponentName.test.(tsxts
TypeScript typesFile.models.tsButton.models.ts
Styles (CSS-in-JS)`ComponentName.styles.(tsjs)`
Storybook`ComponentName.stor(iesy).(tsx

HTML

NameConventionExample
Data Attributeskebab-casedata-testid="button-element"
pathkebab-casewww.fairfx.com/this/is-a-path/

TypeScript

NameConventionExample
interfacePascalCaseinterface DescriptiveInterfaceName
variablescamelCaseconst descriptiveVariableName
functioncamelCasedescriptiveFunctionName(){ ... }
classPascalCaseclass DescriptiveClassName { ... }
typePascalCasetype DescriptiveTypeName
enumsPascalCaseenum DescriptiveEnumName { CONSTANT_A, CONSTANT_B, CONSTANT_C }
constantCONSTANT_CASEDESCRIPTIVE_CONSTANT_NAME

React

NameConventionExample
Component Props InterfacePascalCasePropsComponentNameProps
Component State InterfacePascalCaseStateComponentNameState
Component Copy InterfacePascalCaseCopyComponentNameCopy

Function Component

jsx
import React, { FunctionComponent } from 'react'
const DescriptiveComponentName: FunctionComponent<IDescriptiveComponentNameProps> = (
props
) => {
return ()
}

Class Component

jsx
import React, { Component } from 'react'
class DescriptiveComponentName<
IDescriptiveComponentNameProps,
IDescriptiveComponentNameState
> extends Component {
render () {
return ()
}
}

Code Structure

The objective of this document is to help when structuring your code, to make the codebase more consistent, reusable and easy to read.

This is a guide on how to structure your code.

Linting and code styling ๐Ÿ’…

  • โ—๏ธCode to be formatted using prettier
  • โ€ผ๏ธ All code should follow the TypeScript standard and always make use of types

React

Composability

react_composition_vs_inheritance

Components should ideally be composable, this makes them more flexible and reusable.

General rules about writing new components ๐Ÿšฆ

A standard practice is to avoid having too much functionality in one page with gigantic renders. Each file should have 1 set of functionality. Everything else should be broken into a new component and be included as a child.

Generic

Imports

Avoid * imports, it's best to explicitly define what you want to export.

Types

Avoid a type of any it is normally not allowed.

Spread Syntax

Spread_Syntax

Use nested spread syntax when appropriate. Code should be readable, don't use nested spread syntax if it becomes hard to read.

Preferable Example โœ…

tsx
class MyComponent extends Component {
public render() {
const {
myProp,
nestedProps: { myNestedProp },
} = this.props
}
}

Also Good โœ…

tsx
class MyComponent extends Component {
public render() {
const { myProp, nestedProps } = this.props
const { myNestedProp } = nestedProps
}
}

Ok, if it's only referenced once โœ…

tsx
class MyComponent extends Component {
public render() {
return this.props.nestedProps.myNestedProp.myMoreNestedProp
}
}

File Structure rules ๐Ÿšจ๐Ÿ‘ฎ

Description โ„น๏ธ

These rules must be followed by all team members in order to have a consistent and well structured codebase.

Pages

/src/client/pages
/PageName
index.ts
PageName.tsx
PageName.test.tsx
PageName.schema.json
/OtherPageName
OtherPageName.tsx

Components should by default be placed in /components directory.

Components should be grouped into folders logically. If they are only used once and they are used within another component, they should be colocated with their parent component.

Example:

/src/client/components
/ParentComponent
index.ts
ParentComponent.story.ts
ParentComponent.styles.ts
README.md
/ChildComponent
ChildComponent.tsx
ChildComponent.models.ts
ChildComponent.styles.ts
ChildComponent.test.tsx
ChildComponent.validate.ts
/OtherChildComponent
index.ts
OtherChildComponent.tsx
OtherChildComponent.test.tsx
README.md
/ReusableComponent
index.ts
README.md
ReusableComponent.tsx
ReusableComponent.story.ts
ReusableComponent.test.tsx
/SomeOtherComponentOnlyUsedOnce
index.ts
README.md
SomeOtherComponentOnlyUsedOnce.tsx
SomeOtherComponentOnlyUsedOnce.story.ts
SomeOtherComponentOnlyUsedOnce.test.tsx

๐Ÿ‘ฉ๐Ÿปโ€๐Ÿซ Storybook

Components should be built and tested with a ComponentName.story.tsx and have a README.md file included.

๐Ÿ‘ฉ๐Ÿปโ€๐Ÿ”ฌ Test

Where possible ComponentName.test.tsx other files like utils will need a UtilName.test.ts.

๐Ÿ’๐Ÿปโ€โ™€๏ธ Styled Component

Separate styles from the main code, styles should live in ComponentName.styles.ts.

๐Ÿ‘ท๐Ÿปโ€โ™€๏ธ Models

Separate interfaces and types from the main code, models should live in ComponentName.models.ts

Want to make your own site like this?
Try gatsby-theme-code-notes by Zander Martineau.
Notes on code. My second brain, by Zander Martineau.