store_ai_front/.trellis/spec/frontend/quality-guidelines.md

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

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.

// ✅ 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.