67 lines
3.1 KiB
Markdown
67 lines
3.1 KiB
Markdown
# Quality Guidelines
|
|
|
|
> Principles and standards to ensure code maintainability, reliability, and performance.
|
|
|
|
---
|
|
|
|
## Code Style & Consistency
|
|
|
|
### 1. Naming Conventions (React Specific)
|
|
- **Event Handlers**: Use the `handle` prefix for functions that handle events (e.g., `handleSubmit`, `handleInputChange`).
|
|
- **Callback Props**: Use the `on` prefix for props that represent events (e.g., `<Child onSuccess={handleSuccess} />`).
|
|
- **Boolean Variables**: Use prefixes like `is`, `has`, `should` (e.g., `isLoading`, `hasError`, `shouldRender`).
|
|
|
|
### 2. Modern JavaScript Features
|
|
- **Optional Chaining (`?.`)**: Always use optional chaining when accessing properties of potentially null/undefined objects (especially API responses).
|
|
- **Nullish Coalescing (`??`)**: Use `??` instead of `||` when you specifically want to handle `null` or `undefined` but allow `0` or `""`.
|
|
- **Destructuring**: Use destructuring for props and objects to keep code concise.
|
|
|
|
---
|
|
|
|
## Async & Data Handling
|
|
|
|
### 1. Asynchronous Patterns
|
|
- **Async/Await**: Prefer `async/await` over `.then()` for better readability.
|
|
- **Error Handling**: Every async operation must be wrapped in a `try...catch` block.
|
|
|
|
### 2. Waiting & Loading States
|
|
- **User Feedback**: Every asynchronous action (like an API call) must have an associated **loading state**.
|
|
- **Preventing Race Conditions**: Ensure that multiple rapid clicks on a "Submit" button are handled (e.g., by disabling the button during `loading`).
|
|
|
|
```tsx
|
|
const handleSubmit = async () => {
|
|
setLoading(true);
|
|
try {
|
|
const res = await api.saveData(formData);
|
|
// handle success
|
|
} catch (error) {
|
|
// handle error (e.g., show a toast)
|
|
} finally {
|
|
setLoading(false);
|
|
}
|
|
};
|
|
```
|
|
## React Best Practices
|
|
### 1.Component Logic
|
|
- Early Returns: Use early returns in functions and components to avoid deeply nested if statements.
|
|
- Pure Functions: Keep logic that doesn't depend on React state outside the component function or in a utils file.
|
|
### 2.Rendering Performance
|
|
- Key Prop: Never use the array index as a key prop if the list can change (add/remove/reorder). Use unique IDs.
|
|
- Expensive Calculations: Wrap expensive calculations in useMemo.
|
|
### 3.Clean JSX
|
|
- Avoid Inline Logic: If a ternary operator or logical expression in JSX is too complex, extract it into a variable or a helper function.
|
|
- Fragment Usage: Use <>...</> (Fragments) to avoid unnecessary DOM nodes.
|
|
---
|
|
## Defensive Programming
|
|
- API Robustness: Never assume the backend will return the exact data structure expected. Always provide fallbacks.
|
|
```ts
|
|
// ✅ Good: Defensive and clear
|
|
const userName = data?.user?.profile?.name ?? 'Guest';
|
|
|
|
// ❌ Bad: Fragile
|
|
const userName = data.user.profile.name;
|
|
```
|
|
## Maintenance & Documentation
|
|
- Meaningful Comments: Don't comment what the code is doing (the code should be self-explanatory); comment why a certain non-obvious approach was taken.
|
|
- Dead Code: Remove all console.log, commented-out code, and unused variables before submitting a Pull Request.
|
|
- Complexity: If a component exceeds 250 lines, it is a strong signal that it needs to be refactored into smaller sub-components. |