desktop-team-doc 0.1.0

package/content/tools/skills/frontend-develop/references/coding-standards.md

@@ -0,0 +1,275 @@
+# Coding Standards Reference
+
+This document provides a quick reference for coding standards including formatting rules, naming conventions, and code style. For complete details, refer to the project's full coding standards.
+
+## Formatting Rules
+
+### Prettier Configuration
+
+**Key Rules**:
+- **Indentation**: 2 spaces (not tabs)
+- **Line Length**: Maximum 120 characters
+- **Semicolons**: Always use semicolons
+- **Quotes**: Single quotes for strings
+- **Trailing Commas**: As per Prettier defaults
+- **No trailing whitespace**
+- **No indentation on empty lines**
+
+**Note**: Run `npm run eslint` before committing to ensure code quality.
+
+### ESLint Rules
+
+Follow ESLint rules in `.eslintrc.json`. Common rules:
+- No unused variables
+- No console.log in production code
+- Prefer const over let
+- Prefer arrow functions for callbacks
+
+## Naming Conventions
+
+### Files and Directories
+
+| Type | Convention | Example |
+|------|-----------|---------|
+| React Components | `PascalCase.tsx` | `AppButton.tsx`, `EditableText.tsx` |
+| Hooks | `camelCase.ts` (starts with "use") | `useInputStatus.ts`, `useGearMenuStore.ts` |
+| Utilities | `camelCase.ts` | `constants.ts`, `utils.ts` |
+| Stores | `camelCase.ts` (ends with "Store") | `guitarMatchStore.ts`, `pedalGridStore.ts` |
+| Types/Interfaces | `types.ts` or `interfaces.ts` | `types.ts` |
+| Command Files | `camelCase.ts` (ends with "Cmd") | `initMainViewCmd.ts` |
+
+### TypeScript/JavaScript
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Variables | `camelCase` | `userName`, `isLoading` |
+| Functions | `camelCase` | `handleClick`, `fetchData` |
+| React Components | `PascalCase` | `AppButton`, `EditableText` |
+| Interfaces/Types | `PascalCase` | `AppButtonProps`, `EditableTextHandle` |
+| Type Aliases | `PascalCase` (prefix `T`) | `TKnobProps` |
+| Constants | `UPPER_SNAKE_CASE` | `MAX_BUFFER_SIZE`, `DEFAULT_FRAMES` |
+| Enums | `PascalCase` (values `camelCase`) | `enum Status { active, inactive }` |
+| Props Types | Component + `Props` | `AppButtonProps` |
+| Handler Types | Component + `Handle` | `EditableTextHandle` |
+
+### CSS Classes (TailwindCSS)
+
+- **Design System**: `.x-` prefix (e.g., `.x-btn`, `.x-red-dot`)
+- **Utilities**: `.pg-` prefix (e.g., `.pg-scroll-bar`)
+- **Typography**: Semantic naming (e.g., `.heading-14`, `.body-16`, `.x-heading-4`)
+
+## Code Style Conventions
+
+### Braces (Always Use)
+
+**Rule**: Always use braces for functions and control statements.
+
+**Bad**:
+```typescript
+if (isOpen) closeModal();
+else if (isSaveDialogShowed) setIsSaveDialogShowed(false);
+```
+
+**Good**:
+```typescript
+if (isOpen) {
+  closeModal();
+} else if (isSaveDialogShowed) {
+  setIsSaveDialogShowed(false);
+}
+```
+
+**Exception**: Early returns/guards on one line:
+```typescript
+if (!inputData) return;
+processData1(inputData.data1);
+processData2(inputData.data2);
+```
+
+### API Client Standards
+
+- **Use Axios**: Standardize on `axios` for all API calls
+- **Exception**: `XMLHttpRequest` is used for native command communication only
+
+**Example**:
+```typescript
+import axios from 'axios';
+
+const fetchUserData = async (userId: string) => {
+  try {
+    const response = await axios.get(`/api/users/${userId}`);
+    return response.data;
+  } catch (error) {
+    console.error('Failed to fetch user data:', error);
+    throw error;
+  }
+};
+```
+
+## TypeScript Standards
+
+### Type Safety
+
+- **Strict Mode**: Enable `noImplicitAny: true`
+- **Avoid `any`**: Use specific types or `unknown` when type is truly unknown
+- **Type Imports**: Use `type` keyword for type-only imports
+
+```typescript
+import type { MousePos } from '@/src/utils/mouseRx/types';
+```
+
+### Interface vs Type
+
+- **Interfaces**: For object shapes, especially props and public APIs
+- **Type Aliases**: For unions, intersections, and complex types
+
+### Function Return Types
+
+Always explicitly define return types:
+
+```typescript
+const processData = (): string => {
+  return 'result';
+};
+```
+
+## React Patterns
+
+### Component Structure Order
+
+1. **Imports** (external → internal → types → styles)
+2. **Type Definitions** (Props interfaces, handler types)
+3. **Component Declaration** (arrow functions or `forwardRef`)
+4. **Hooks** (`useState`, `useRef`, `useEffect`)
+5. **Handlers** (Event handlers, callbacks)
+6. **Render Helpers** (Small render functions)
+7. **Return Statement** (JSX)
+
+### Props Destructuring
+
+Destructure props in function parameters:
+
+```typescript
+const Component = ({ value, onChange }: EditableTextProps) => {
+  // Component logic
+};
+```
+
+### Props Spreading (Use Sparingly)
+
+**Avoid indiscriminate props spreading**:
+
+**Bad**:
+```typescript
+function Comp({ dataA, ...props }) {
+  return <div {...props} />;
+}
+```
+
+**Good**:
+```typescript
+function Comp({ dataA, onClick, onMouseMove, role }) {
+  return <div onClick={onClick} onMouseMove={onMouseMove} role={role} />;
+}
+```
+
+## Import Organization
+
+### Import Order
+
+1. External libraries (React, third-party)
+2. Internal modules (aliased with `@/`)
+3. Types (using `import type`)
+4. Relative imports
+5. Styles (if any)
+
+**Example**:
+```typescript
+import React, { useState, useEffect } from 'react';
+import { twMerge } from 'tailwind-merge';
+import clsx from 'clsx';
+
+import ClickOutsideHandler from '@/src/components/dumbs/click-outside-handler';
+import { useParameterComponentProps } from '@/src/components/shared/store';
+
+import type { MousePos } from '@/src/utils/mouseRx/types';
+import type { AppButtonProps } from './types';
+
+import './styles.css';
+```
+
+### Path Aliases
+
+- **Configure `@/` to point to project root**
+- **Use `@/src/` for source imports**
+- **Avoid `@src/` pattern** (looks like npm org package)
+
+**tsconfig.json configuration**:
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./*"]
+    }
+  }
+}
+```
+
+## Event Handlers
+
+### Naming
+
+- Prefix with `handle` for event handlers: `handleClick`, `handleChange`, `handleSubmit`
+- Prefix with `on` for prop callbacks: `onClick`, `onChange`, `onSubmit`
+
+### Async Handlers
+
+```typescript
+const handleSubmit = async () => {
+  try {
+    await submitData();
+  } catch (error) {
+    console.error('Submit failed:', error);
+  }
+};
+```
+
+## Error Handling
+
+- Use try-catch for async operations
+- Log errors appropriately
+- Show user-friendly error messages
+- Handle edge cases gracefully
+
+## Commenting Policy
+
+See [Team-wide Coding Conventions](../team-wide.md#commenting-policy) for the team's minimalist commenting policy.
+
+### Frontend-Specific Guidelines
+
+- **Complex State Logic**: Comment non-obvious state management patterns
+- **Workarounds**: Document workarounds with explanation
+- **Type Assertions**: Explain why type assertion is necessary if non-obvious
+- **Magic Numbers**: Use named constants instead of comments
+
+## Quick Reference Checklist
+
+When writing code, ensure:
+
+- [ ] 2-space indentation, single quotes
+- [ ] Explicit return types on functions
+- [ ] Always use braces for functions and control statements
+- [ ] Props destructured in parameters
+- [ ] `import type` for type-only imports
+- [ ] Path aliases use `@/src/` pattern
+- [ ] TailwindCSS for styling (primary)
+- [ ] Event handlers prefixed with `handle`
+- [ ] Axios for API calls
+- [ ] No indiscriminate props spreading
+- [ ] Semantic HTML and accessibility
+
+## References
+
+For complete details, see:
+- **Full Coding Standards**: `desktop-team-documentation/instructions/coding-conventions/frontend.md`
+- **Team-wide Standards**: `desktop-team-documentation/instructions/coding-conventions/team-wide.md`