---
description: Code Style Guide
---

# Laravel 10 – Repository Pattern  
## Strict Coding Rules (Anti-Trash & Anti-Overengineering)

This document defines mandatory rules to prevent meaningless files, useless comments, and over-engineered architecture.

---

## 0. Core Principle

Do not create code unless it introduces real behavior.  
Do not write comments to compensate for bad code.

Readable code replaces comments.  
Behavior justifies files.

---

## 1. Comment Rules (VERY STRICT)

Forbidden:
- Comments repeating code meaning
- Comments describing method names
- Placeholder comments
- TODO without ticket reference

Allowed only to explain WHY:
- Architectural decisions
- Non-obvious side effects
- Constraints or workarounds

---

## 2. File Creation Rules

Do NOT create files:
- For clean structure only
- For symmetry
- For future assumptions
- To wrap a single call

---

## 3. When a New File Is Allowed

At least ONE condition must be true:
1. Real business rules exist
2. Logic reused in 2+ places
3. Side effects exist (transaction, cache, events)

---

## 4. Repository Rules

Repositories MAY:
- Query data
- Filter
- Paginate
- Cache

Repositories MUST NOT:
- Validate
- Apply business rules
- Format responses
- Check permissions

---

## 5. Service Layer Rules

Service allowed only if:
- Uses multiple repositories
- Manages transactions
- Coordinates caching
- Enforces domain rules

Proxy-only services are forbidden.

---

## 6. Controller Rules

Controllers MAY:
- Accept Request
- Call Service or Repository
- Return Response

Controllers MUST NOT:
- Contain business logic
- Query database directly

---

## 7. Interface Rules

Do NOT create interfaces if only one implementation exists.

Interfaces allowed only when:
- Multiple implementations exist
- Cache on/off switching
- Required for testing

---

## 8. Helper Rules

Forbidden:
- Business logic in helpers

Allowed:
- String
- Date
- Array utilities

---

## 9. Naming Rules

Forbidden:
handle, process, execute, run, doSomething

Required:
publishCourse, syncStudentProgress, calculateFinalScore

---

## 10. Exception Rules

Forbidden:
throw new Exception()

Required:
Explicit domain-specific exceptions

---

## 11. Folder Structure Rules

Avoid over-fragmentation.

One concept = minimal files.

---

## 12. File Count Sanity Check

CRUD feature <= 5 files is acceptable.  
More than 10 files indicates over-engineering.

---

## 13. Code Review Rejection Checklist

Reject if:
- File has no behavior
- Service only proxies calls
- Comment explains WHAT not WHY
- Interface has one implementation
- File exists for future use

---

## 14. AI Enforcement Rules

- Do not create files without behavior
- Do not generate meaningless comments
- Do not create proxy layers
- Prefer fewer, clearer files
- Reject over-engineering

---

## 15. Final Rule

Architecture serves behavior.  
If code has no clear reason to exist, remove it.