首页

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

@@ -0,0 +1,67 @@
+# 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.