# 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.