[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,125 +2,247 @@
|
||||
id: wiki-2026-0508-naming-conventions
|
||||
title: Naming Conventions
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: []
|
||||
aliases: [Code Naming, Identifier Conventions]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.92
|
||||
tags: [uncategorized]
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [code-style, conventions, readability]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-08
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: multi
|
||||
framework: cross-language
|
||||
---
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
Naming Conventions(명명 규칙)은 코드의 가독성, 유지보수성, 그리고 협업 효율성을 높이기 위해 파일, 컴포넌트, 변수 등의 이름을 짓는 합의된 표준이다. 명확한 규칙을 통해 코드의 역할을 직관적으로 파악하게 하며, 특히 운영체제 간의 대소문자 구분 차이로 인한 빌드 오류를 방지하는 실질적인 엔지니어링 목적을 갖는다.
|
||||
# Naming Conventions
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
1. **파일 및 폴더 (kebab-case)**
|
||||
- 대소문자 구분이 없는 OS(Windows, macOS)와 엄격한 OS(Linux) 간의 CI/CD 빌드 충돌을 막기 위해 소문자와 하이픈을 사용하는 `kebab-case`를 권장한다.
|
||||
- Next.js의 예약어(`page.js`, `layout.js`)나 라우트 그룹(`(folder)`) 등의 규칙을 준수한다.
|
||||
2. **React 컴포넌트 및 타입 (PascalCase)**
|
||||
- 컴포넌트명과 TypeScript의 Type/Interface, Enum 등은 첫 글자를 대문자로 하는 `PascalCase`를 사용하여 일반 변수와 구별한다.
|
||||
3. **변수, 함수, 프로퍼티 (camelCase)**
|
||||
- JavaScript 표준에 따라 첫 단어는 소문자로 시작하는 `camelCase`를 사용한다.
|
||||
- Boolean 값은 `is`, `has`, `should` 접두사를, 이벤트 핸들러는 `handle`, `on` 접두사를 붙여 의미를 명확히 한다.
|
||||
4. **커스텀 훅 (use 접두사)**
|
||||
- React의 Rules of Hooks를 준수하기 위해 반드시 `use` 접두사로 시작하는 `camelCase`를 사용한다.
|
||||
5. **상수 (UPPER_SNAKE_CASE)**
|
||||
- 변경되지 않는 고정 값은 대문자와 밑줄을 사용하는 `UPPER_SNAKE_CASE`로 작성하여 식별력을 높인다.
|
||||
6. **Git 및 워크플로우**
|
||||
- 브랜치명: `{type}/{ticket-id}-{description}` 형식의 소문자 kebab-case 사용.
|
||||
- 커밋 메시지: Conventional Commits(`feat:`, `fix:` 등) 형식을 준수하여 추적성을 확보한다.
|
||||
## 매 한 줄
|
||||
> **"매 names 매 code 매 most-read interface — 매 정확/예측가능/검색가능 매 핵심 경제재"**. Casing styles (camelCase, snake_case, PascalCase, kebab-case, SCREAMING_SNAKE) 매 language idiom 매 정해지며 매 semantic precision (boolean prefix `is/has`, async suffix, no abbreviation) 매 readability 의 진짜 lever.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **엄격함 vs 유연성**: 너무 복잡한 네이밍 규칙은 개발자의 인지 부하를 늘리고 생산성을 저하시킬 수 있으므로, 팀 규모에 맞는 적절한 수준의 합의가 필요하다.
|
||||
- **자동화 도구의 한계**: ESLint 등으로 많은 네이밍 규칙을 강제할 수 있으나, '의미론적(Semantic) 적절성'까지는 도구가 판단할 수 없으므로 여전히 코드 리뷰가 중요하다.
|
||||
- **프레임워크 제약**: 사용 중인 프레임워크(예: Next.js)의 예약어 규칙이 팀의 컨벤션과 충돌할 경우, 프레임워크의 규칙을 우선시해야 시스템 오류를 방지할 수 있다.
|
||||
## 매 핵심
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
### Related Concepts (Auto-Linked)
|
||||
* [[Abstract_Syntax_Tree]]
|
||||
* [[Branching Strategies]]
|
||||
* [[ESLint]]
|
||||
* [[Feature-Sliced_Design]]
|
||||
* [[JavaScript]]
|
||||
* [[Next.js]]
|
||||
* [[Prettier]]
|
||||
* [[React]]
|
||||
* [[Research]]
|
||||
### 매 casing styles
|
||||
- **camelCase**: `userName` — JS/TS variables, Java methods.
|
||||
- **PascalCase**: `UserProfile` — types, classes, React components.
|
||||
- **snake_case**: `user_name` — Python, Ruby, Rust variables, SQL.
|
||||
- **kebab-case**: `user-profile` — file names (web), CSS classes, URLs, npm packages.
|
||||
- **SCREAMING_SNAKE**: `MAX_RETRIES` — constants 매 모든 language.
|
||||
|
||||
### Related Concepts
|
||||
- **kebab-case**: 파일 시스템 호환성을 위한 소문자-하이픈 조합 (관계: 물리적 저장 표준)
|
||||
- **Conventional Commits**: 변경 이력 가독성을 위한 표준 (관계: 협업 워크플로우 규칙)
|
||||
- **PascalCase**: 컴포넌트 및 타입 식별을 위한 대문자 시작 조합 (관계: 논리적 식별 표준)
|
||||
### 매 language idioms
|
||||
- **JavaScript/TypeScript**: camelCase var, PascalCase type/class/component, SCREAMING_SNAKE const, kebab-case file.
|
||||
- **Python**: snake_case 매 모든 매 (var/func/module), PascalCase class, SCREAMING_SNAKE const.
|
||||
- **Rust**: snake_case var/func/module, PascalCase type/trait/enum, SCREAMING_SNAKE const.
|
||||
- **Go**: camelCase (unexported) / PascalCase (exported), 매 underscore X.
|
||||
- **Java/C#**: camelCase var/method, PascalCase class, SCREAMING_SNAKE const.
|
||||
- **CSS**: kebab-case (BEM block__element--modifier).
|
||||
|
||||
### Deeper Research Questions
|
||||
1. OS별 대소문자 인식 차이가 실제 프로덕션 빌드 환경에서 유발하는 'Silent failure' 사례와 그 디버깅 방법은?
|
||||
2. 네이밍 규칙 준수가 TypeScript의 타입 추론 성능이나 트리 쉐이킹(Tree Shaking) 효율에 간접적인 영향을 미치는가?
|
||||
3. 대규모 리팩토링 시, 기존의 네이밍 컨벤션을 일괄 변경하기 위한 AST(Abstract Syntax Tree) 기반 자동화 도구 활용 방안은?
|
||||
4. `isVisible` vs `showComponent`와 같이 상태 중심 네이밍과 명령 중심 네이밍 중 어떤 것이 유지보수에 더 유리한가?
|
||||
5. 다국어 지원(i18n) 프로젝트에서 키값(Key) 네이밍을 도메인 중심으로 짓는 것과 페이지 중심으로 짓는 것의 트레이드오프는?
|
||||
### 매 응용
|
||||
1. Code review enforcement (linter rules).
|
||||
2. Refactor automation (regex-safe renaming).
|
||||
3. API design (URL kebab vs JSON camelCase).
|
||||
4. Cross-language interop (serialization mapping).
|
||||
|
||||
### Practical Application Contexts
|
||||
- **협업 환경 구축**: ESLint 및 Prettier 설정을 통해 팀원 전체가 동일한 네이밍 케이스를 사용하도록 자동 강제.
|
||||
- **이슈 추적**: 브랜치명에 티켓 ID를 포함하여 Jira/GitHub Issues와 코드를 유기적으로 연결.
|
||||
## 💻 패턴
|
||||
|
||||
### Adjacent Topics
|
||||
- **Clean Code & Meaningful Names**
|
||||
- **Feature-Sliced Design (FSD)**
|
||||
- **Git Branching Strategies**
|
||||
### Boolean naming
|
||||
```ts
|
||||
// 매 BAD
|
||||
const loading = true
|
||||
const visible = false
|
||||
const adult = true
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
// 매 GOOD — predicate-style prefix
|
||||
const isLoading = true
|
||||
const isVisible = false
|
||||
const isAdult = true
|
||||
const hasPermission = true
|
||||
const canEdit = false
|
||||
const shouldRefresh = true
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Function naming (verb-first)
|
||||
```ts
|
||||
// 매 BAD
|
||||
function user(id) { /* ambiguous: getter? setter? */ }
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
// 매 GOOD
|
||||
function getUser(id) { /* read */ }
|
||||
function fetchUser(id) { /* network */ }
|
||||
function createUser(data) { /* persist */ }
|
||||
function updateUser(id, patch) { /* mutate */ }
|
||||
function deleteUser(id) { /* remove */ }
|
||||
function isUserActive(user) { /* predicate */ }
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Async suffix / event handler prefix
|
||||
```ts
|
||||
// 매 GOOD
|
||||
async function loadDataAsync() { } // 매 optional, depends on team
|
||||
const handleClick = () => { } // React handler
|
||||
const onClick = () => { } // 매 component prop
|
||||
```
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
### Collection plurality
|
||||
```ts
|
||||
// 매 BAD
|
||||
const user = [u1, u2, u3] // 매 array 인지 single 인지 모호
|
||||
const userList = [...] // "List" suffix 매 redundant
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
// 매 GOOD
|
||||
const users = [u1, u2, u3]
|
||||
const usersById = new Map() // shape suffix
|
||||
const usersByEmail = new Map()
|
||||
```
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
### Constants vs config
|
||||
```ts
|
||||
// 매 SCREAMING_SNAKE — 매 immutable primitive
|
||||
const MAX_RETRIES = 3
|
||||
const API_BASE_URL = 'https://api.example.com'
|
||||
|
||||
// 매 camelCase — 매 config object (still const)
|
||||
const apiConfig = {
|
||||
baseUrl: 'https://api.example.com',
|
||||
timeout: 5000,
|
||||
}
|
||||
```
|
||||
|
||||
### File naming
|
||||
```
|
||||
# 매 React/Vue components
|
||||
UserProfile.tsx # PascalCase (component)
|
||||
user-profile.css # kebab-case (asset)
|
||||
|
||||
# 매 Python
|
||||
user_profile.py # snake_case
|
||||
test_user_profile.py # 매 test_ prefix
|
||||
|
||||
# 매 Go
|
||||
user_profile.go # snake_case
|
||||
user_profile_test.go # _test.go suffix
|
||||
|
||||
# 매 docs
|
||||
README.md # SCREAMING (convention)
|
||||
naming-conventions.md # kebab-case
|
||||
```
|
||||
|
||||
### Avoid abbreviation (with exceptions)
|
||||
```ts
|
||||
// 매 BAD
|
||||
const usr = ...
|
||||
const cfg = ...
|
||||
const btnClkHndlr = ...
|
||||
|
||||
// 매 GOOD
|
||||
const user = ...
|
||||
const config = ...
|
||||
const handleButtonClick = ...
|
||||
|
||||
// 매 OK exceptions — universal abbreviations
|
||||
id, url, http, json, db, api, ui, css, html, ms (millisecond), idx (loop index)
|
||||
```
|
||||
|
||||
### Domain prefix vs suffix
|
||||
```ts
|
||||
// 매 prefix — 매 grouping advantage (autocomplete)
|
||||
function userGet() {}
|
||||
function userCreate() {}
|
||||
function userDelete() {}
|
||||
|
||||
// 매 suffix — 매 verb-first natural
|
||||
function getUser() {}
|
||||
function createUser() {}
|
||||
function deleteUser() {}
|
||||
|
||||
// 매 modern preference: verb-first (suffix domain)
|
||||
```
|
||||
|
||||
### URL / API naming
|
||||
```
|
||||
GET /api/users ← kebab plural noun
|
||||
GET /api/users/{id}
|
||||
POST /api/users/{id}/orders
|
||||
GET /api/order-statuses ← kebab compound
|
||||
|
||||
# 매 NOT
|
||||
GET /api/getUser ← verb in URL — 매 X
|
||||
GET /api/User ← PascalCase — 매 X
|
||||
GET /api/user_list ← snake — 매 X (web convention)
|
||||
```
|
||||
|
||||
### JSON field convention
|
||||
```jsonc
|
||||
// 매 JS-consuming API: camelCase
|
||||
{ "userId": 1, "createdAt": "2026-05-10" }
|
||||
|
||||
// 매 Python/Ruby ecosystem: snake_case
|
||||
{ "user_id": 1, "created_at": "2026-05-10" }
|
||||
|
||||
// 매 cross-platform: pick one + serialize-time transform
|
||||
```
|
||||
|
||||
### Linter enforcement (ESLint)
|
||||
```jsonc
|
||||
// .eslintrc.json
|
||||
{
|
||||
"rules": {
|
||||
"@typescript-eslint/naming-convention": [
|
||||
"error",
|
||||
{ "selector": "variable", "format": ["camelCase", "UPPER_CASE"] },
|
||||
{ "selector": "function", "format": ["camelCase"] },
|
||||
{ "selector": "typeLike", "format": ["PascalCase"] },
|
||||
{ "selector": "enumMember", "format": ["UPPER_CASE"] },
|
||||
{ "selector": "variable", "modifiers": ["const"], "types": ["boolean"], "format": ["camelCase"], "prefix": ["is", "has", "can", "should"] }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Style |
|
||||
|---|---|
|
||||
| JS/TS variable | camelCase |
|
||||
| JS/TS type/class | PascalCase |
|
||||
| JS/TS const primitive | SCREAMING_SNAKE |
|
||||
| JS/TS const object | camelCase |
|
||||
| Python var/func | snake_case |
|
||||
| File (web asset/url) | kebab-case |
|
||||
| File (component) | PascalCase |
|
||||
| File (Python) | snake_case |
|
||||
| Boolean | `is/has/can/should` prefix |
|
||||
| Predicate function | `isX/hasX/canX` |
|
||||
| URL path | kebab plural noun, no verb |
|
||||
|
||||
**기본값**: 매 language idiom 매 따라 매 + 매 boolean 매 predicate prefix + 매 verb-first function.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[Code-Style]] · [[Readability]]
|
||||
- 변형: [[BEM]] (CSS) · [[Hungarian-Notation]] (legacy)
|
||||
- 응용: [[ESLint]] · [[Linter-Configuration]] · [[API-Design]]
|
||||
- Adjacent: [[Clean-Code]] · [[Self-Documenting-Code]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: 매 새 codebase setup, 매 cross-language API design, 매 linter config, 매 code review checklist.
|
||||
**언제 X**: 매 short script (overhead), 매 generated code (machine-driven naming OK).
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **Hungarian notation**: `strName`, `iCount` — 매 type system 매 redundant.
|
||||
- **Cryptic abbreviation**: `getUsrPrf()` — 매 readability 의 X.
|
||||
- **Inconsistent casing**: 매 mixed style 매 한 codebase — 매 cognitive overhead.
|
||||
- **Verb in URL**: `/api/getUser` — 매 RESTful 의 X.
|
||||
- **Plural type name**: `Users` 매 single user type — 매 misleading.
|
||||
- **Negation prefix**: `isNotReady` — 매 double-negative 위험 — `isReady` + `!isReady` 사용.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Airbnb Style Guide, PEP 8, Google Style Guides, Rust API guidelines).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — casing matrix + boolean/function/file/URL conventions + ESLint enforcement |
|
||||
|
||||
Reference in New Issue
Block a user