Welcome to our project! This README outlines the conventions and best practices we follow to ensure our code is clean, consistent, and easy to maintain. Adherence to these guidelines is crucial for collaboration and the long-term health of the codebase.
- General Principles
- Front-End Conventions
- Library Conventions
- Back-End Conventions
- Helpers Conventions
- General
- File Names & Structures
- Best Coding Practices
- TSDoc Guide
- Clarity and Consistency: Clear, consistent names aid in understanding and maintaining the code.
- Descriptive Names: Names should be intuitive and describe the entity's functionality.
- Established Patterns: Follow patterns for ease of integration and maintenance.
- UI Components:
PascalCase
for both filenames and class names (e.g.,UserProfile.tsx
). - React Hooks: Prefixed with
use
andcamelCase
(e.g.,useAuth.ts
).
- CSS Classes: Use
kebab-case
for names. Example:primary-button
. - Be semantic: Name classes based on their purpose rather than their appearance, e.g.,
.btn-danger
over.red-button
. - BEM (Block Element Modifier): A common methodology where the class is named following a
block__element--modifier
format, e.g.,.button__icon--small
- Classes, Types, and Enums: Use
PascalCase
. Example:LinkedList
,UserType
.
- Controllers:
PascalCase
withController
suffix;kebab-case
for filenames (e.g.,user.controller.ts
). - Services:
PascalCase
withService
suffix (e.g.,UserService
). - Middleware:
PascalCase
withMiddleware
suffix (e.g.,AuthMiddleware
).
- Helpers/Utilities:
verbNoun
format incamelCase
for functions and filenames (e.g.,formatDate.ts
).
- Variables: Use
CamelCase
. Example:userData
. - Interfaces: Prefix with
I
and usePascalCase
. Example:IUser
. - Enums: Use
PascalCase
in singular form. Example:UserRole
. - Global Constants: Use
UPPER_SNAKE_CASE
. Example:DEFAULT_USER_ROLE
. - Environment Variables: Use
UPPER_SNAKE_CASE
. Example:API_BASE_URL
. - Assets/Images/Icons: Name with
kebab-case
. Example:logo-icon.svg
. - Test Filenames: Match the tested file's filename with
.test.ts
(e.g.,dateHelpers.test.ts
). - Documentation: Use TSDoc for clarity.
- File Names: use the same convention as the default export (e.g. for a class
UserProfile
useUserProfile.tsx
or for a functiontransformUser()
useuserFunction.ts
). - File Names for Helpers: Name the file based on the general functionality or category of the helpers. Use
camelCase
. For example, if the file contains various string manipulation functions, you could name itstringHelpers.ts
orauthHelpers.ts
. - Folders: Use kebab-case for general folders. Example:
user-profile
. - Group by Feature: Organize files in feature-specific folders. For instance, all user-related entities such as
UserList
,UserProfile
, andUserEdit
can be within ausers
directory. - Folder Size: If a folder has more than
10
files then generally, try to group some tother into sub-directories. - Avoid Redundancy: Don't repeat folder names in the file name, e.g., if you have a
user/
folder, you don't needuser/user-list.component.ts
; justlist.component.ts
is clearer.
- TSDoc: For all public interfaces, classes, functions, and methods.
- Linting: Try ensure as many coding conventions and styles are enforced with our linters. This is defined in the files
.prettierrc.json
,tsconfig.json
and.eslintrc.json
. By downloading the suggestedVSCode
extensions (specified in.vscode/extensions.json
) your code will be automatically formatted to these rules.
-
When to Add: On public interfaces, classes, functions, methods.
-
Minimum Include: Description, parameters, return type.
-
Example:
/** * Calculates the sum of two numbers. * @param {number} a - The first number. * @param {number} [b] - The second number (optional). * @returns {number} The sum of the two numbers. */ function add(a: number, b?: number): number { return a + b ?? 0; }