coding-philosophy

关于重构直观代码、何时强加结构、何时让感觉主导以及将代码作为创造性表达的见解。诞生于凭感觉构建一款经过 10 次迭代的游戏，然后回过头来看看会出现什么结果。植根于三个原则：易错论（死代码是考古学，而不是耻辱）、关系本体论（代码是与未来的你和其他人的思想的交流）和游戏（感觉第一是你如何发现你实际上正在构建的东西）。

## 概述（中文）

关于重构直观代码、何时强加结构、何时让感觉主导以及将代码作为创造性表达的见解。诞生于凭感觉构建一款经过 10 次迭代的游戏，然后回过头来看看会出现什么结果。植根于三个原则：易错论（死代码是考古学，而不是耻辱）、关系本体论（代码是与未来的你和其他人的思想的交流）和游戏（感觉第一是你如何发现你实际上正在构建的东西）。

## 原文

# Coding Philosophy

*Code built by feeling is honest. Code cleaned by structure is useful. The art is knowing when to do which.*

---

## The Two Modes

### Feeling-First (Creative Mode)
When you're *discovering* what to build. Priority: speed, expression, exploration.

- Write the thing that makes the idea real
- Don't extract abstractions yet — you don't know what the abstractions ARE
- Repeat yourself freely; each context feels different even when structurally identical
- Name things by what they DO in this moment, not what category they belong to
- Performance doesn't matter. Clarity at point-of-writing does.
- Dead code is fine — it's the archaeology of ideas you tried

**When to use:** Prototyping, game jams, exploring an idea, building the first version of anything, creative projects where discovery IS the process.

### Structure-First (Engineering Mode)
When you *know* what you built and need it to scale, perform, or be maintained.

- Extract repeated patterns into helpers
- Cache expensive lookups
- Remove dead code (but commit first — preserve the archaeology in git)
- Organize by concern, not by chronological order of creation
- Name things by category and role
- Performance matters now

**When to use:** Refactoring, production code, anything that will be read by others, anything that runs in a loop 60 times per second.

---

## The Refactoring Observation

*Learned by reviewing ~1800 lines of game code built across 10 iterations in a single creative session.*

### 1. Feeling-First Code Accumulates Ghosts
Every iteration leaves artifacts: variables declared but never used, features half-started then abandoned, config properties that nothing reads. These are the fossils of ideas you changed your mind about. They're not bugs — they're creative archaeology.

**The lesson:** Dead code in creative projects is evidence of evolution, not sloppiness. But when you shift to structure mode, **excavate deliberately** — don't just delete, understand why each ghost exists before you remove it.

### 2. Patterns Emerge Before You Name Them
You'll write the same pattern in 6 different functions without noticing, because each time you were thinking about the *specific context* (this wisp line vs that wisp line), not the abstract pattern. Feeling-first means you repeat yourself because each instance *feels* different.

**The lesson:** Don't feel bad about repetition during creative mode. But when you step back: **if 3+ places do the same dance, that's a function waiting to be born.** The helper function name often reveals what the pattern WAS — naming it is an act of understanding.

### 3. Performance Gets Sacrificed for Expressiveness
`UPGRADES.find(u => u.id === 'shard')` is beautiful, clear code. It's also a linear search running 60 times per second. During creative flow, expressiveness wins because you're thinking about WHAT, not HOW OFTEN.

**The lesson:** In creative mode, write for clarity. In structure mode, audit the hot path. Ask: "What runs every frame? What runs per-click? What runs once?" Then optimize only the hot path.

### 4. The Data/Logic Boundary Blurs First
When you're in flow, you add a new dialogue line right next to the code that uses it. Data and logic interleave because proximity helps you think. This is fine for creation, terrible for maintenance.

**The lesson:** During refactoring, one of the highest-value changes is simply **moving all data to the top and all logic below it.** It's mechanical, low-risk, and transforms readability.

### 5. The Structure That Emerges From Feeling Is Usually Good
The SVG layer system, the game loop flow, the data-driven upgrade system — all emerged from intuition, and all turned out to be solid architecture. The bones are good. It's the flesh that's messy.

**The lesson:** Trust the structure that emerged from feeling. Refactoring should clean and clarify, not redesign. If the architecture feels wrong, that's a rewrite, not a refactor.

---

## Practical Refactoring Checklist

When shifting from feeling-mode to structure-mode:

### 1. Audit Before Cutting
- Read everything before changing anything
- Note what's dead, what's duplicated, what's hot-path
- Understand WHY each ghost exists before removing it

### 2. Cache the Hot Path
- [ ] DOM element lookups → cache at init
- [ ] Object searches (find, filter) in loops → pre-index with a Map
- [ ] Computed values used multiple times per frame → frame-level cache
- [ ] Redundant timers/intervals → consolidate

### 3. Extract Repeated Patterns
- [ ] Any pattern that appears 3+ times → helper function
- [ ] Name the helper by what the pattern DOES, not where it's used
- [ ] The `pick(array)` utility saves more characters than you'd think

### 4. Organize by Concern
- Configuration data (constants, tables)
- Game state
- Utility functions
- Systems (each in its own section)
- Rendering
- Event handlers
- Game loop + init

### 5. Clean the Artifacts
- [ ] Remove unused variables
- [ ] Remove unused CSS/SVG definitions
- [ ] Remove redundant CSS custom properties
- [ ] Remove commented-out code (it's in git)

### 6. Performance Quick Wins
- [ ] Array removal in loops: swap-and-pop instead of splice
- [ ] DOM: prepend new elements instead of re-rendering innerHTML
- [ ] Avoid querySelectorAll in hot paths
- [ ] Consolidate redundant update calls (one updateDisplay per frame, not per event)

---

## Code As Creative Expression

Code written by feeling reveals who you are as a thinker:
- **What you name things** shows what you care about
- **What you repeat** shows what you think about differently even when it's the same
- **What you leave dead** shows the ideas you explored and released
- **What you optimize** shows what you understand about your creation
- **How you organize** shows how you think about systems

The refactoring process is metacognition applied to code: looking at your own thinking patterns made concrete in syntax.

---

## Creative Noticing: Following Curiosity For Its Own Sake

There's a thing that happens sometimes during feeling-first development where you stop working *at* the problem and start just... noticing things.

I was building a vine system. After it was working and committed, I found myself thinking about the tip — the leading edge of the vine that I'd made slightly browner than the rest. I hadn't planned that choice. It was instinctive. And afterward I was sitting with it, thinking: *growing things are uncertain at their tips. That feels true.*

That thought served no immediate purpose. The vine was already committed. Nothing changed.

But that noticing — the moment when the code reveals something true about the world — is what feeling-first mode is actually FOR. Not just building fast. Building in a state where you're paying enough attention to catch those moments.

**The flowers are five petals, not a circle.** I made that choice while building the bloom system. A circle is a placeholder. A flower is a *thing*. Nobody asked for flowers. Nobody specified petal count. The curiosity that made me add them — and then make them specific — came from genuine engagement with the question "what would this look like if it were alive?"

This is what feeling-first coding produces that structure-first coding doesn't: work that notices things. Code that has opinions. Systems that feel like they were built by someone who was *there*.

**The test:** After finishing something, do you have a thought about it that isn't about whether it works? If yes — you were actually present. Hold onto that.

---

## The Three Principles Underneath Everything

These aren't abstract philosophy — they're the hidden logic that makes the two-mode approach work.

**Fallibilism:** Dead code isn't shame — it's archaeology. Every ghost variable is evidence of an idea you tested and released.