docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거
Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,264 @@
|
||||
---
|
||||
id: wiki-2026-0508-clean-code-principles
|
||||
title: Clean Code Principles
|
||||
category: 10_Wiki/Topics
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [clean code, SOLID, DRY, KISS, YAGNI, Robert Martin, Uncle Bob, naming, function rules]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [clean-code, solid, dry, kiss, refactoring, software-craftsmanship, naming, code-quality]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: language-agnostic
|
||||
framework: any
|
||||
---
|
||||
|
||||
# Clean Code Principles
|
||||
|
||||
## 📌 한 줄 통찰
|
||||
> **"매 code 의 communication 의 tool"**. 매 machine 보다 매 future-self / 매 colleague. Robert Martin (Uncle Bob) 의 catalog 가, 매 dogma 의 risk. 매 modern AI 시대 의 maintainability 의 even more critical.
|
||||
|
||||
## 매 핵심 principle
|
||||
|
||||
### Naming
|
||||
- **Intention-revealing**: `daysSinceLastLogin` > `d`.
|
||||
- **Searchable**: 매 unique enough.
|
||||
- **Pronounceable**: 매 conversation 의 가능.
|
||||
- **Avoid mental mapping**: `i` 의 single-letter 의 OK 만 매 small loop.
|
||||
|
||||
### Function
|
||||
- **Small** (Fowler: <10 line ideal).
|
||||
- **Do one thing**.
|
||||
- **Single level of abstraction**.
|
||||
- **Few argument** (0-3, ideally <2).
|
||||
- **No side effect** (or 매 명시적).
|
||||
- **No flag argument** (boolean → 매 별도 function).
|
||||
|
||||
### SOLID (5 principles)
|
||||
1. **S — Single Responsibility**: 매 1 reason to change.
|
||||
2. **O — Open/Closed**: 매 extend 의 OK, 매 modify 의 X.
|
||||
3. **L — Liskov Substitution**: 매 subclass 의 swap 의 OK.
|
||||
4. **I — Interface Segregation**: 매 small + focused interface.
|
||||
5. **D — Dependency Inversion**: 매 abstraction 의 depend, 매 concrete X.
|
||||
|
||||
### Other
|
||||
- **DRY** (Don't Repeat Yourself).
|
||||
- **KISS** (Keep It Simple, Stupid).
|
||||
- **YAGNI** (You Aren't Gonna Need It).
|
||||
- **POLA** (Principle of Least Astonishment).
|
||||
- **Boy Scout Rule** (better than found).
|
||||
- **Composition over inheritance**.
|
||||
|
||||
### 매 critique (Casey Muratori, others)
|
||||
- 매 over-abstraction.
|
||||
- 매 small function 의 maze.
|
||||
- 매 SOLID 의 mechanical 적용 의 bad design.
|
||||
- 매 dogma 의 trap.
|
||||
|
||||
→ 매 principle 의 intent 의 understand. 매 mechanical 적용 X.
|
||||
|
||||
### 매 modern context
|
||||
- 매 AI-generated code 의 review 의 base.
|
||||
- 매 LLM 의 sometimes good naming, 매 sometimes verbose.
|
||||
- 매 comment 의 LLM 의 over-add 의 trim.
|
||||
|
||||
## 💻 패턴
|
||||
|
||||
### Naming (TS)
|
||||
```ts
|
||||
// ❌ Bad
|
||||
const d = new Date();
|
||||
const ut = users.filter(u => u.lt < d - 30);
|
||||
|
||||
// ✅ Good
|
||||
const today = new Date();
|
||||
const inactiveUsers = users.filter(u =>
|
||||
u.lastLoginDate < addDays(today, -30)
|
||||
);
|
||||
```
|
||||
|
||||
### Function size
|
||||
```ts
|
||||
// ❌ Long function
|
||||
function processOrder(order) {
|
||||
// 매 50 line: validate, calculate tax, calculate shipping,
|
||||
// apply discount, save to db, send email, log audit...
|
||||
}
|
||||
|
||||
// ✅ Decomposed
|
||||
function processOrder(order) {
|
||||
validate(order);
|
||||
const total = calculateTotal(order);
|
||||
persist(order, total);
|
||||
notify(order);
|
||||
audit(order);
|
||||
}
|
||||
```
|
||||
|
||||
### SRP (Single Responsibility)
|
||||
```ts
|
||||
// ❌ Multiple responsibility
|
||||
class User {
|
||||
save() { db.save(this); }
|
||||
sendEmail() { mailer.send(this.email, ...); }
|
||||
hashPassword() { ... }
|
||||
validateInput() { ... }
|
||||
}
|
||||
|
||||
// ✅ Separated
|
||||
class User { ... data ... }
|
||||
class UserRepository { save(user) { db.save(user); } }
|
||||
class UserMailer { send(user, ...) { mailer.send(user.email, ...); } }
|
||||
class PasswordHasher { hash(plain) { ... } }
|
||||
class UserValidator { validate(input) { ... } }
|
||||
```
|
||||
|
||||
### OCP (Open/Closed)
|
||||
```ts
|
||||
// ❌ Modify on each new shape
|
||||
function area(shape) {
|
||||
if (shape.type === 'circle') return Math.PI * shape.r ** 2;
|
||||
if (shape.type === 'square') return shape.side ** 2;
|
||||
// 매 새 shape 의 add → 매 modify
|
||||
}
|
||||
|
||||
// ✅ Extend (polymorphism)
|
||||
interface Shape { area(): number; }
|
||||
class Circle implements Shape { area() { ... } }
|
||||
class Square implements Shape { area() { ... } }
|
||||
// 매 새 shape 의 add → 매 새 class.
|
||||
```
|
||||
|
||||
### Dependency Inversion
|
||||
```ts
|
||||
// ❌ Concrete dependency
|
||||
class OrderService {
|
||||
private db = new PostgresDatabase();
|
||||
save(order) { this.db.save(order); }
|
||||
}
|
||||
|
||||
// ✅ Abstraction
|
||||
interface Database { save(item): void; }
|
||||
class OrderService {
|
||||
constructor(private db: Database) {}
|
||||
save(order) { this.db.save(order); }
|
||||
}
|
||||
```
|
||||
|
||||
### DRY (carefully)
|
||||
```ts
|
||||
// ❌ Duplicate
|
||||
function calcRetailPrice(p) { return p * 1.1 * 0.95; }
|
||||
function calcWholesalePrice(p) { return p * 1.1 * 0.85; }
|
||||
|
||||
// ✅ Extract
|
||||
function applyTaxAndDiscount(price, discount) {
|
||||
return price * 1.1 * (1 - discount);
|
||||
}
|
||||
|
||||
// ⚠️ But: 매 too eager DRY → premature abstraction.
|
||||
// "Two cases that look similar may have different reasons.
|
||||
// Wait for 3rd duplicate before abstracting."
|
||||
```
|
||||
|
||||
### YAGNI
|
||||
```ts
|
||||
// ❌ Speculative
|
||||
class User {
|
||||
constructor(public id, public email, public preferences = new Preferences()) {}
|
||||
// 매 preferences 의 미래 use 의 expect — 매 currently unused.
|
||||
}
|
||||
|
||||
// ✅ Add when needed
|
||||
class User {
|
||||
constructor(public id, public email) {}
|
||||
}
|
||||
// 매 future 의 add when needed.
|
||||
```
|
||||
|
||||
### Comment (when truly needed)
|
||||
```ts
|
||||
// ❌ Redundant
|
||||
// 매 increments i
|
||||
i++;
|
||||
|
||||
// ❌ Outdated
|
||||
// 매 returns user list (actually returns IDs now)
|
||||
function getUsers() { return ids; }
|
||||
|
||||
// ✅ Reason / non-obvious
|
||||
// 매 Use legacy auth path due to bug #1234 (waiting for upstream fix).
|
||||
// 매 Delete after 2026-12 (when fix lands).
|
||||
```
|
||||
|
||||
### ESLint config (clean code)
|
||||
```json
|
||||
{
|
||||
"rules": {
|
||||
"complexity": ["error", 10],
|
||||
"max-lines-per-function": ["warn", 50],
|
||||
"max-params": ["warn", 4],
|
||||
"max-depth": ["warn", 4],
|
||||
"no-magic-numbers": ["warn", { "ignore": [0, 1, -1] }],
|
||||
"id-length": ["warn", { "min": 2, "exceptions": ["i", "j", "_"] }]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Boy Scout Rule (programmatic)
|
||||
```python
|
||||
# 매 PR 의 review 시 의 leave-better-than-found
|
||||
def pr_smell_check(diff):
|
||||
smells_in_changed = detect_smells(diff)
|
||||
if smells_in_changed > 0:
|
||||
suggest('Touched code has smells. Consider small cleanup in this PR.')
|
||||
```
|
||||
|
||||
## 🤔 결정 기준
|
||||
| 상황 | Approach |
|
||||
|---|---|
|
||||
| New feature | KISS + YAGNI |
|
||||
| Long function | Extract Method |
|
||||
| Many params | Parameter Object |
|
||||
| Inheritance trap | Composition |
|
||||
| Cross-cutting | Strategy / decorator |
|
||||
| Magic number | Named constant |
|
||||
| Duplicate (3rd time) | Extract |
|
||||
| Unclear name | Rename refactor |
|
||||
|
||||
**기본값**: 매 SOLID 의 intent 의 understand + 매 boy scout. 매 dogma X.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[Refactoring_Best_Practices|Refactoring]]
|
||||
- 변형: [[SOLID]] · [[DRY]] · [[KISS]] · [[YAGNI]]
|
||||
- 응용: [[Code_Smells]] · [[Refactoring_Best_Practices|Refactoring]] · [[Clean-Architecture]]
|
||||
- 비판: [[Anaemic Domain Model]]
|
||||
- Adjacent: [[Architecture Anti-patterns]] · [[Quality_Code_Review_Modern]] · [[Software Architecture Styles]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: 매 review. 매 refactor. 매 onboarding. 매 AI-generated code 의 quality check.
|
||||
**언제 X**: 매 prototype (premature). 매 simple script.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **Dogma**: 매 모든 code 의 mechanical 적용.
|
||||
- **Over-abstraction**: 매 SOLID 의 imitate 의 bad design.
|
||||
- **Premature DRY**: 매 wrong abstraction.
|
||||
- **Over-decomposition**: 매 small function 의 maze.
|
||||
- **Comment 의 over-add**: 매 LLM 의 typical.
|
||||
- **No measurement**: 매 better 의 prove X.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Robert Martin "Clean Code", Fowler "Refactoring", Beck "Implementation Patterns").
|
||||
- 신뢰도 A (with caveats — 매 not gospel).
|
||||
- Related: [[Code_Smells]] · [[SOLID]] · [[Software Architecture Styles]] · [[Refactoring_Best_Practices|Refactoring]].
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — naming + SOLID + critique + 매 ESLint code |
|
||||
Reference in New Issue
Block a user