Knowledge Base

Appearance

Introduction ​

The goal of this document is to compile the development practices for the three main monorepos, aiming for more consistent and standardized development.

This document should remain straightforward and include only the universally agreed-upon elements. Other aspects will be addressed in retrospectives or during specific discussions.

During code reviews, developers must ensure adherence to established rules, making pragmatic exceptions as necessary. These rules will also be enforced by the linter where possible.

🔴: Rejected – To be reviewed in retrospective
🚧: Candidate – Currently under discussion
🟢: Approved by the Team – Consensus achieved

Development Guidelines ​

1. Naming Conventions ​

1.1 🟢 Files and folders ​

Files and folders names must be all lowercase and may include dashes (-).

🚧In backend project, file names should directly correspond to their default export. For example, the task-service.ts file should have a default export like export default class TaskService {...}. Any additional named exports should be linked to the main export. source. Moreover the default export must not be a mere function.

eg: src/modules/domain/item-import-report/item-import-report.service.ts eg: src/components/features/user/user.tsx

Rationales
  • Eliminates issues with non-case-sensitive file systems or configurations, such as those found in Linux/Windows, URLs, and similar environments.
  • Enhances typing efficiency: eliminates the need to hold one key while pressing another.
  • Improves readability: ensures clearer separation of words, enhancing overall clarity.
  • Recommended by Google and VueJS

1.2 🟢 File Extensions ​

In certain cases, to better delineate the structure and functionality within our projects, we adopt specific file extensions. For instance, in NestJS projects, we use:

  • .service.ts
  • .controller.ts
  • .module.ts
  • .dto.ts
  • .test.ts
  • .unit.ts

In frontend development, particularly with Redux, we employ

  • .slice.ts
Rationales
  • Predominantly Utilized Convention in the Current Codebase
  • Convention used in NestJS Official Documentation : example

1.3 🟢 Class, Interface, Enum ​

  • Class, interface and enum are written in PascaleCase.
  • No extension like .enum.ts or .interface.ts
  • Interfaces should be named clearly and intuitively without including 'Interface' in the name. The use of 'Facade' as a suffix is permissible but not obligatory, reserved for cases where it clarifies the design pattern being applied.
  • Enum keys are in UPPERCASE

eg: TaskService, TaskContext eg:

export enum TaskTimeoutPolicy {
    RETRY = 'RETRY',
    TIMEOUT = 'TIME_OUT_WF',
    ALERT = 'ALERT_ONLY'
}

export enum TaskRetryLogic {
    FIXED = 'FIXED',
    EXPONENTIAL = 'EXPONENTIAL_BACKOFF'
}
Rationales
  • Predominantly Utilized Convention in the Current Codebase
  • Book 'Clean Code' by Robert C Martin

1.4 🟢 Environment variable ​

  • Environment variable names must be entirely UPPERCASE and may include underscores ( _ ).
  • They should be clear and free of unnecessary words. eg:
# Avoid
environment:
   - "main_maria_host=..."

# Recommended
environment:
   - "MARIA_HOST=..."
Rationales
  • Predominantly Utilized Convention in the Current Codebase
  • Guided by architectural decisions

1.5 🚧Plural and Lists ​

For filenames and variables that represent a collection or plural concept, use the 's' suffix instead of 'List' or the singular form, e.g. packages, tableIds.

Rationales
  • Clean Code Robert C. Martin

1.6 🚧Id ​

IDs should be named either id or <myObject>Id.

eg.

// Avoid 
function getTable(table) {...}

// Recommended 
function getTable(id) {...}

1.7 🟢 Errors ​

For enhanced clarity and to ensure the uniformity of error messaging across the application, the following convention should be used :

A. Formulation of Error Titles: ​

  • In English: Adopt the template {Trigger Component} {Action} Error for structuring error messages.
    Eg: "Table Navigation Error", "Table Edition Error", "Cell Action Error".
  • In French: Follow the template Erreur d'{Action} de {Déclencheur} for formulating error messages.
    Eg: "Erreur de navigation vers la table", "Erreur d'édition de la table", "Erreur d'édition sur la cellule".
  • Ideally, translations are managed on the frontend side, and APIs should send raw data, including codes and descriptions.

B. Error Message Display: ​

  • Prefer using Ant Design's notification.error over message.error for the display of error messages to ensure a consistent user experience.
jsx
notification.error({
    message: context.t('Item edition error'),
    description: context.t('Attachment must be smaller than {limit} MB', { limit }),
});
Rationales
  • This approach is driven by the goal to standardize development practices and maintain consistency in user interface behavior as per architectural guidelines.
  • Translations should be managed on the frontend, ensuring a clear separation of concerns, centralization of translation resources, and enabling dynamic localization based on the user's preferences or settings.

2. Folder and File Structure ​

2.1 🟢 Use LF endline ​

Adopt LF (Line Feed) for line endings to ensure consistency across platforms and avoid build issues. Some tests file use CRLF to check parsing compatibility.

Rationales
  • Ensures platform-independent consistency as part of our architectural standards.
  • Prevents build failures in certain tools (worker) that do not recognize CRLF as valid line endings.

2.2 🟢 Frontend: Feature-first project structure ​

  • Place specific components used within a single application in /src/features/[my-feature] for feature-specific components,
  • Store common components used across multiple applications, like App, Settings, and Admin, in /lib/features/src/[my-feature] for feature-specific components, or /lib/components (* should be renamed in lib/common/) for shared react component. eg.
packages/
├── app/src/
│   ├── features/
│   │   └── [my-feature]/
│   │       └── ...
│   └── utils/
│       └── ...
└── lib/
    ├── features/
    │   └── src/
    │       ├── auth/
    │       │   └── auth.tsx
    │       └── ...
    └── common*/
        └── ...
Rationales

2.3 🟢 Backend Project Structure ​

  • Store service logic within the /services directory, aligning with NestJS's architectural recommendations.
  • Utilize /utils directory and /domain for shared utilities or entities
Rationales

2.4 🟢 Barrel files ​

Barrel files, typically named index.ts, are used to export multiple components from a directory. In frontend projects, it's recommended to avoid using barrel files (see rationales).

// Not allowed in frontend

// services/index.ts
export * from './service1';
export * from './service2';
export * from './service3';
Rationales
  • When you import from a barrel file, you potentially end up importing the entire module or a large set of components/functions, even if you only need a small part of it. This practice can negate the benefits of lazy loading, as it prevents splitting your code into smaller chunks that can be loaded on demand. Thus, avoiding barrel files can be crucial for enabling effective lazy loading and subsequently optimizing the bundle size.
  • Detailed explanation of the issues can be found in this Vercel article.

3. React usage ​

3.1 🟢 id, data-testid and className naming convention ​

  • Use HyphenCase (KebabCase) for id, data-testid and className eg: <div className='h-100 d-flex flex-direction-column'> eg: <Input.TextArea placeholder='Enter description' data-testid="pipeline-form-input-textarea"/> eg: <div className='app'> eg: <div id="user-profile"></div>
Rationales
  • Predominantly Utilized Convention in the Current Codebase
  • Recommended by Google

3.2 🟢 Component ​

  • Use PascalCase
  • Define components as functions instead of classes
  • Do not use React.FC unless it's necessary eg:
const Greeting = ({ name="" }) => {
  return (<h1>Hello, {name}!</h1>);
}
Rationales

3.3 🟢 Custom Hook ​

  • Use CamelCase for custom hook names.
  • Custom hook names may include verbs to indicate actions, for example: useWakeup for a hook that triggers actions when the browser exits sleep mode.
  • The filename for custom hooks should be prefixed with "use," for example: "use-wakeup.ts"

eg:

const useWakeup = () => {
...
}
Rationales

3.4 🟢 Input and button (data-testid) ​

  • All Input and Button elements should include a data-testid attribute to facilitate End-to-End (E2E) testing.
  • All Input and Button elements should be implemented as Antd components.

eg:

import { Form, Input } from 'antd';

...

<Form.Item {...FormLayouts.itemFormLayout} label='Description' name='description'>
    <Input.TextArea placeholder='Enter description' data-testid="pipeline-form-input-textarea"/>
</Form.Item>
Rationales
  • Guided by architectural decisions.
  • Essential for E2E testing using Playwright.

3.5 🟢 Redux ​

  • Prefix Redux selectors with select, for example, selectAdminConfiguration.
  • Redux slices should be named with a .slice.ts extension, for example: counter.slice.ts.
  • Use the custom hook useAsyncDispatch when you need to call an API that triggers an action or a modification in the Redux store.
  • Example:
jsx
{
  ...
  const asyncDispatch = useAsyncDispatch();
  useEffect(() => {
    const loadAccounts = async () => {
      await asyncDispatch(getAccountsListAsyncAction());
    };
    loadAccounts();
  }, []);
  ...
}

const getAccountsListAsyncAction = () =>
  AsyncActionBuilder({
      actions: {
          load: accountsListSlice.actions.accountsListLoad,
          success: accountsListSlice.actions.accountsListSuccess,
          error: accountsListSlice.actions.accountsListFail
      },
      promise: async () => {
          return getAllPages((page, pageSize) => {
              return HakuClientFinder.LoggedClient().me().myAccounts(page, pageSize);
          });
      }
  });
Rationales
  • Establish uniform development standards
  • Guided by architectural decisions.

3.6 🟢 No Custom CSS ​

To ensure consistency and maintainability in your codebase, adhere to the following principles:

  • Prefer Ant Design Components: Use Ant Design for UI consistency and reduce custom CSS.
  • Fallback to Tailwind Utilities: For specific styling needs not covered by Ant Design, use Tailwind's utility classes.
  • Opt for twin.macro styled component for Complexity: When Tailwind classes clutter your markup, switch to twin.macro for a tidier approach.

twin.macro example:

jsx
// Less ideal: Excessive classes
const Component = () => (
  <div className="flex justify-center items-center p-4 bg-blue-500 hover:bg-blue-700">
    <div className="px-4 bg-red-500">
      {/* ... */}
    </div>
    <div className="px-4 mt-4 bg-blue-500">
      {/* ... */}
    </div>
  </div>
)

// Recommended
const Component = () => (
  <Cell>
    <Header>
      {/* ... */}
    </Header>
    <Description>
      {/* ... */}
    </Description>
  </Cell>
);

const Cell = tw.div`flex justify-center items-center p-4 bg-blue-500 hover:bg-blue-700`;
const Header = tw.div`px-4 bg-red-500`;
const Description = tw.div`px-4 mt-4 bg-blue-500`;
Rationales
  • Maintain a clean and readable codebase
  • Ensures styling consistency across the development team.
  • Avoids the accumulation of unused CSS, enhancing project performance.

3.7 🟢 Translation Guidelines ​

  • Do not use backticks (``) for Strings in context.t() translations (see rationales). Always use single (' ') or double (" ") quotes for string identifiers.
  • Use useContext(I18nContext) for a more standard approach and easier mocking in Storybook instead of getTranslationContext().
    • Example:
jsx
const context = useContext(I18nContext);
context.t('You cannot edit this cell');
Rationales
  • The translation scripts (npm run trad-extract) do not recognize template literals so using them in context.t() will not translate the string. However you can use them for punctuation. eg: context.t('Hello, I`m PL!')

4 Typescript usage ​

4.1🟢 Interface vs Type ​

  • Use interface for public API definitions, object shapes, and component props.
  • Use type for specific values, union types, function types, and event types.
// Using interface for an object shape
export interface Bear {
  name: string;
  food: BearFood;
}

// Using type for union types
type BearFood = MammalFood | FishFood;
Rationales
  • Official typescript documentation: If you would like a heuristic, use interface until you need to use features from type.
  • For more on why interfaces are preferred, see this video(MongoDB dev perspective)

4.2 🟢 Avoid Solo Variables in Conditions ​

Instead of using a variable alone (non boolean) in a condition (e.g., if (x) {...}), prefer explicit checks (e.g., if (x !== 0) {...}) for clarity and to prevent unintended coercion.

  • If posible, use encapsulation condition from Robert C. Martin (Clean Code)

eg.

// Avoid
if (load) { … }

// Recommended
if (load != null) { … }


// Avoid
if (fsm.state === "fetching" && isEmpty(listNode)) { … }

// Recommended
if (shouldShowSpinner(fsm, listNode)) { … }
Rationales
  • Clean Code by Robert C. Martin

4.3 🟢 Avoid Cluttering Your Code with Inferable Types ​

  • Avoid writing type annotations when TypeScript can infer the same type.
  • Ideally your code has type annotations in function/method signatures but not on local variables in their bodies.
  • Consider using explicit annotations for object literals and function return types even when they can be inferred. This will help prevent implementation errors from surfacing in user code.
// Avoid
const person: {
  name: string;
  born: {
    where: string;
    when: string;
  };
  died: {
    where: string;
    when: string;
  }
} = {
  name: 'Sojourner Truth',
  born: {
    where: 'Swartekill, NY',
    when: 'c.1797',
  },
  died: {
    where: 'Battle Creek, MI',
    when: 'Nov. 26, 1883'
  }
};


// Recommended
const person = {
  name: 'Sojourner Truth',
  born: {
    where: 'Swartekill, NY',
    when: 'c.1797',
  },
  died: {
    where: 'Battle Creek, MI',
    when: 'Nov. 26, 1883'
  }
};

// Recommended
interface Product {
  id: string;
  name: string;
  price: number;
}

function logProduct(product: Product) {
  const {id, name, price} = product;
  console.log(id, name, price);
}

// Avoid
function logProduct(product: Product) {
  const {id, name, price}: {id: string; name: string; price: number } = product;
  console.log(id, name, price);
}
Rationales

4.4 🟢 Test : Should... When ​

  • Adopt the 'Should... When' convention for naming test cases to clearly describe expected behavior and specific conditions.
  • Additionally, use describe blocks to group tests, naming them after the service or component being tested for straightforward identification.
describe('UserService', () => {
  it('should return user details when the user ID is valid', () => {
    // Test implementation
  });
});
Rationales
  • Guided by architectural decisions.

4.5 🟢 Any vs Unknown ​

If possible, avoid using any keywords (except if you work with javascript library); consider replacing them with 'unknown'.

// Recommended
export class RowDataCellEditRequest {
    itemId: string;
    fieldKey: string;
    fieldVal: unknown;
    suffix?: string;

    withItem(itemId: string): RowDataCellEditRequest {
        this.itemId = itemId;
        return this;
    }

    withField(fieldKey: string, fieldValue: unknown): RowDataCellEditRequest {
        this.fieldKey = fieldKey;
        this.fieldVal = fieldValue;
        return this;
    }

    withSuffix(suffix: string): RowDataCellEditRequest {
        this.suffix = suffix;
        return this;
    }
}
Rationales

5 Error Management ​

🟢 5.1 Types of Exceptions in the Application ​

  • FrontError: Errors originating from the frontend application.
  • PlError: Errors from Haku endpoints or other APIs.
  • Error: General JavaScript errors not created by the developer.

Examples:

const frontError = new FrontError()
    .withCode(FrontErrorCode.MISSING_STATE)
    .withMessage('Current user local storage path oidc not set');

const plError = new PlError()
    .withCode(PlErrorCode.UNAVAILABLE)
    .withMessage(`Network Error during /whoami`);

🟢 5.2 Exception Levels ​

  • Fatal: Unhandled generic errors generating an ErrorBoundary. These should be captured by Sentry and require investigation.
  • Error: Serious errors preventing functionality, but handled and enriched by the developer (e.g., PlError, FrontError). These should be logged and notified.
  • Warning: Undesirable errors mitigated in the code. These should be logged for later analysis but do not require immediate alerting.

Examples:

// Example with captureError()
const handleSubmit = async (values: FormCreateAccountValues) => {
    setLoading(true);
    try {
        const plAccount = await new AccountService().createAccount(
            {
                companyName: values.companyName,
                subDomain: values.subDomain,
                zone: values.zone
            },
            values.email
        );
        navigate(`/accounts/${plAccount.id}`);
    } catch (err) {
        captureError(err);
        notification.error({ message: `Cannot create account: ${err.message}` });
    }
    setLoading(false);
};

// Example with captureWarning()
const getPickerLocaleFromLanguage = (language: Language) => {
    const found = datepickerLocaleMap.get(language);
    if (found == null) {
        captureWarning(
            new FrontError()
                .withMessage(`No datepicker locale found for language: ${language}`)
                .withCode(FrontErrorCode.USER)
        );
    } else {
        return found;
    }
    return datepickerLocaleMap.get(Language.eng) as PickerLocale;
}

🟢 5.3 Exception Handling ​

  • Error Handling: Display a message to the user, redirect, send to Sentry, etc.
  • Re-throwing Errors: If not handled, the error should be re-thrown without processing, except for adding additional data (e.g., URL, application state).
  • Anti-pattern to Avoid: Never handle and re-throw an error simultaneously. This complicates debugging and may hide underlying issues.
  • API Calls: Ideally, API calls should be within a try/catch block.

Examples:

// Avoid
try { 
  /* Code that may throw error */ 
} catch(err) {
  // Do not do both!
  captureError(err);
  throw err;
}

// Recommended
try { 
  /* Code that may throw error */ 
} catch(err) {
  captureError(err);
}

// Recommended
try { 
  /* Code that may throw error */ 
} catch(err) {
  throw err;
}

// Recommended
try { 
  /* Code that may throw error */ 
} catch(err) {
  throw new FrontError().withCode(FrontErrorCode.UNKNOWN).withMessage(err.message);
}

🟢 5.4 Front Error Code ​

  • USER: User action error that does not affect the application beyond displaying a notification.
  • UNKNOWN: Unidentified error.
  • BAD_USAGE: Incorrect usage of a component not intended for that specific purpose.
  • MISSING_PARAM: A required HTTP request parameter is missing.
  • MISSING_STATE: A required React or Redux state is missing.
  • NOT_FOUND: A required data was not found after an algorithmic search.
  • ACCESS_FORBIDDEN: User does not have permission to access the component.
  • ALREADY_EXISTS: Duplication is not allowed.
  • BAD_FORMAT: Error during data conversion.
  • INVALID_STATE: A required React or Redux state is present but incorrect.
  • INVALID_PARAM: A required parameter is present but incorrect.
  • NOT_INITIALIZED: Component or configuration is not initialized.
  • MISSING_PROPS: A required prop for a React component is missing.
  • NOT_IMPLEMENTED: Functionality is not implemented.