# Hook Guidelines

> This document defines the standards for creating and using custom hooks to ensure logic reuse, readability, and separation of concerns.

---

## Overview

In this project, Hooks are the primary way to manage side effects and encapsulate business logic. We use hooks to keep components focused solely on the UI, while the "how it works" is abstracted away.

---

## Custom Hook Patterns

### 1. Complex Logic Extraction (Business Hooks)
When a feature involves complex states or multiple related methods, extract them into a custom hook. A component should ideally only "call" logic, not define it.

- **Example (Comment Feature)**: Instead of putting the comment list, the loading state, and the `handleSubmit` function inside the component, move them to `useComments`.
- **Benefit**: This makes the component code much cleaner and allows the logic to be tested or reused independently.

```tsx
// use-comments.ts
export const useComments = (articleId: string) => {
  const [comments, setComments] = useState<any[]>([]);
  const [loading, setLoading] = useState(false);

  const postComment = async (content: string) => {
    // Logic for posting a comment...
  };

  /**
   * Internal logic to fetch comments
   */
  const fetchComments = async () => {
    // Logic for fetching...
  };

  return { comments, loading, postComment, refresh: fetchComments };
};
```
### 2.Utility Hooks (Shared Logic)
Utility hooks are for common browser interactions or state monitoring that are not tied to a specific business feature.
- `State Monitoring`: Hooks that trigger actions when a specific state changes.
- `Event Listeners`: Hooks for window resizing, scroll detection, or clicking outside an element.
- `Example`: useWindowSize, useDebounce, useLocalStorage.

----
## Naming Conventions
- Prefix: All hooks must start with the use prefix (e.g., useAuth, useTableData).
- File Naming: Use kebab-case for the filename (e.g., use-comment-list.ts).
- Function Naming: Use camelCase for the function name (e.g., useCommentList).

---
## Organization
- Global Hooks: Place reusable utility hooks in src/hooks/.
- Feature Hooks: Place hooks specific to a single page or module within that module's own hooks/ directory (e.g., src/app/dashboard/hooks/).

---
## Best Practices
### 1.Return Types
For hooks returning multiple values, we prefer Objects over Arrays for better extensibility and clarity.
```tsx
// ✅ Recommended: Object return (naming is explicit)
const { data, loading } = useData();

// ❌ Avoid: Array return (unless it mimics useState)
const [data, loading] = useData();
```
### 2. Memoization
Use useCallback and useMemo within hooks for any functions or complex values that are passed as dependencies to other hooks or as props to memoized components.

### 3.Commenting
Every custom hook should have a JSDoc comment explaining its purpose and the parameters it accepts.
```tsx
/**
 * Monitors the scroll position and returns a boolean if it exceeds a threshold.
 * @param threshold - The scroll pixel value to trigger the change.
 */
export const useScrollTrigger = (threshold: number) => {
  // logic...
};
```

## Common Mistakes
- Heavy Components: Putting API calls and state transitions directly in reveal.tsx instead of a hook.
- Dependency Lies: Forgetting to include variables used inside useEffect or useCallback in the dependency array.
- Over-abstraction: Creating a custom hook for something that is only 2 lines of code and only used once. Only extract when it adds clarity or reusability.