dragoon0x/10x-designer/code-craft

Code Craft

Mission

Write code that is easy to understand, difficult to misuse, and safe to change.

Code is an interface for future engineers.

1. Clarity first

Prefer:

• obvious control flow
• descriptive names
• local reasoning
• explicit state
• small coherent functions
• predictable data flow

Avoid cleverness that saves lines while increasing cognitive cost.

2. Abstraction timing

Abstract when:

• repetition is real
• responsibility is stable
• reuse is meaningful
• the abstraction reduces total complexity

Do not abstract merely because two pieces currently look similar.

3. State ownership

Ask:

• Who owns this state?
• Who needs to read it?
• Who needs to mutate it?
• How long should it live?
• Can it be derived?

Prefer derived state when possible.

Avoid duplicated sources of truth.

4. Error handling

Errors should be:

• detected
• represented
• surfaced appropriately
• recoverable where possible
• logged/diagnosed where appropriate

Never swallow errors merely to make the UI appear successful.

5. Boundaries

Make boundaries explicit:

• API
• storage
• network
• persistence
• component
• module
• platform

Validate data at boundaries.

Do not spread assumptions about external data throughout the system.

6. Dependencies

Before adding one:

• inspect existing dependencies
• inspect platform capabilities
• assess maintenance
• assess bundle/runtime cost
• assess API stability
• assess whether a local implementation is genuinely simpler

7. Refactoring

Refactor when it improves the requested work.

Do not use feature work as an excuse for unrelated cleanup.

When refactoring:

• preserve behavior
• keep scope clear
• validate after meaningful steps

8. Testing

Test behavior, not implementation trivia.

Prioritize:

• primary workflow
• important edge cases
• state transitions
• failure recovery
• shared primitives
• public boundaries

9. Concurrency

Look for:

• duplicate requests
• stale responses
• race conditions
• cancellation
• stale UI
• out-of-order updates

10. Resource lifecycle

Check:

• event listeners
• timers
• subscriptions
• observers
• streams
• temporary files
• network requests
• workers

Every acquired resource needs an appropriate release path.

11. Code review

Ask:

• Can another engineer understand this?
• Can this fail silently?
• Is there duplicated truth?
• Is the abstraction earning its existence?
• What happens under repeated use?
• What happens with invalid data?

Completion criteria

Code craft is complete when:

• behavior is correct
• structure is understandable
• abstractions are justified
• failure paths exist
• resource lifecycles are safe
• tests cover meaningful behavior
• future changes remain reasonably safe