binhtranquoc/project-standards

Project Standards

This skill provides the foundational coding standards that apply to ALL projects regardless of tech stack.

When to Use

• Use this skill for ANY coding task
• This skill is the foundation that other stack-specific skills build upon
• Always read this skill FIRST before reading stack-specific skills

Instructions

1. Analyze Environment First

Before applying any rules, READ the dependency files:

• package.json (Node/TS projects)
• composer.json (PHP/Laravel)
• go.mod (Go projects)
• requirements.txt / pyproject.toml (Python)

Principle: Respect legacy. If the project already uses a specific library, USE IT.

---

SOLID Principles (Strict Enforcement)

S - Single Responsibility

A class/function must have ONE and only ONE reason to change.

• Violation: A UserService that handles DB queries AND sends Emails.
• Fix: Split into UserRepository and EmailNotificationService.

O - Open/Closed

Open for extension, closed for modification. Use Interfaces/Abstract classes.

L - Liskov Substitution

Subtypes must be substitutable for their base types.

I - Interface Segregation

Clients should not be forced to depend on interfaces they do not use. Split large interfaces.

D - Dependency Inversion

Depend on abstractions, not concretions.

• Rule: Always inject dependencies via Constructor. Never use new Class() inside business logic.

---

Clean Code Core

• DRY (Don't Repeat Yourself): Logic duplicated > 2 times must be extracted.
• KISS (Keep It Simple, Stupid): Simplest solution is usually best. Avoid Over-Engineering.
• YAGNI (You Ain't Gonna Need It): Do not implement features "just in case".

---

Function/Method Rules

• Max Lines: < 30 lines ideally.
• Max Params: < 3 parameters. Use DTO/Object if more needed.
• No Boolean Flags: Split functions instead of createUser(isSuperAdmin: boolean).

---

Naming Conventions

By Language

| Category | JS/TS | Python | Go | PHP | |---|---|---|---|---| | Files | kebab-case | snake_case | snake_case | PascalCase | | Classes | PascalCase | PascalCase | PascalCase | PascalCase | | Functions | camelCase | snake_case | camelCase | camelCase | | Variables | camelCase | snake_case | camelCase | $camelCase | | Constants | SCREAMING_SNAKE | SCREAMING_SNAKE | PascalCase | SCREAMING_SNAKE |

Structural Naming

• Helpers: Module-specific support. Location: modules/<name>/helpers/
• Common/Shared: Generic reusable. Location: src/common/ or src/shared/
• Services: Must end with Service, Handler, or UseCase.
• DTOs/Types: Must include suffix (e.g., user.dto.ts, order_response.go).

---

Comments & Documentation

Commenting Rules

• Zero-Comment Policy: Do not comment obvious code.
• Complex Logic Only: Only comment algorithms or counter-intuitive decisions.
• NO ICONS/EMOJIS: Absolutely NO decorations in comments. Raw text only.
  • Bad: // Fast calculation function
  • Good: // Uses binary search for O(log n) complexity.

Function Documentation (JSDoc/GoDoc/Docstring)

• Public API Only: Only document exported functions.
• Concise: 1-2 sentences max. Do not restate parameter names.

// Bad: Redundant
/**
 * Adds two numbers.
 * @param a First number
 * @param b Second number
 * @returns The sum
 */
const add = (a: number, b: number) => a + b;

// Good: Necessary context only
/**
 * Calculates tax based on local VAT rules (2024 reform).
 */
const calculateTax = (price: number, region: string) => { ... }

---

RESTful API Standards

HTTP Verbs

• GET - Read (Idempotent, Safe)
• POST - Create
• PUT - Full Update
• PATCH - Partial Update
• DELETE - Remove

Status Codes

• 200 OK - Success (Read/Update)
• 201 Created - Success (Create)
• 204 No Content - Success (Delete)
• 400 Bad Request - Validation Error
• 401 Unauthorized - Auth missing
• 403 Forbidden - No permission
• 404 Not Found - Resource not exist
• 500 Internal Server Error - App crash

Response Envelope

{
  "success": true,
  "data": {},
  "meta": { "page": 1, "limit": 10, "total": 100 },
  "error": { "code": "ERROR_CODE", "message": "...", "details": [] },
  "timestamp": "2024-01-20T10:00:00Z"
}

URL Naming

• Collection: /users (Plural, kebab-case)
• Resource: /users/123
• Sub-resource: /users/123/orders

---

Database Standards

• Naming: snake_case for tables/columns.
• Primary Keys: UUID (distributed) or BigInt.
• Audit Fields: created_at, updated_at, deleted_at mandatory.

---

Folder Structure

Option A: Feature-based (Recommended)

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── api/
│   │   └── index.ts
│   └── dashboard/

Option B: Layer-based (Classic)

src/
├── components/
├── pages/
├── services/
├── utils/
└── hooks/