ed3dai/ed3d-plugins/coding-effectively

Coding Effectively

Required Sub-Skills

ALWAYS REQUIRED:

• howto-functional-vs-imperative - Separate pure logic from side effects
• defense-in-depth - Validate at every layer data passes through

CONDITIONAL: Use these sub-skills when applicable:

• howto-code-in-typescript - TypeScript code
• howto-code-in-rust - Rust code
• howto-develop-with-postgres - PostgreSQL database code
• programming-in-react - React frontend code
• writing-good-tests - Writing or reviewing tests
• property-based-testing - Tests for serialization, validation, normalization, pure functions

Property-Driven Design

When designing features, think about properties upfront. This surfaces design gaps early.

Discovery questions:

Common design questions these reveal:

• "What about deleted/deactivated entities?"
• "Case-sensitive or not?"
• "Stable sort or not? Tie-breaking rules?"
• "Which algorithm? Configurable?"

Surface these during design, not during debugging.

Core Engineering Principles

Correctness Over Convenience

Model the full error space. No shortcuts.

• Handle all edge cases: race conditions, timing issues, partial failures
• Use the type system to encode correctness constraints
• Prefer compile-time guarantees over runtime checks where possible
• When uncertain, explore and iterate rather than assume

Don't:

• Simplify error handling to save time
• Ignore edge cases because "they probably won't happen"
• Use any or equivalent to bypass type checking

Error Handling Philosophy

Two-tier model:

1. User-facing errors: Semantic exit codes, rich diagnostics, actionable messages
2. Internal errors: Programming errors that may panic or use internal types

Error message format: Lowercase sentence fragments for "failed to {message}".

Good: failed to connect to database: connection refused
Bad:  Failed to Connect to Database: Connection Refused
 
Good: invalid configuration: missing required field 'apiKey'
Bad:  Invalid Configuration: Missing Required Field 'apiKey'

Lowercase fragments compose naturally: "operation failed: " + error.message reads correctly.

Pragmatic Incrementalism

• Prefer specific, composable logic over abstract frameworks
• Evolve design incrementally rather than perfect upfront architecture
• Don't build for hypothetical future requirements
• Document design decisions and trade-offs when making non-obvious choices

The rule of three applies to abstraction: Don't abstract until you've seen the pattern three times. Three similar lines of code is better than a premature abstraction.

File Organization

Descriptive File Names Over Catch-All Files

Name files by what they contain, not by generic categories.

Don't create:

• utils.ts - Becomes a dumping ground for unrelated functions
• helpers.ts - Same problem
• common.ts - What isn't common?
• misc.ts - Actively unhelpful

Do create:

• string-formatting.ts - String manipulation utilities
• date-arithmetic.ts - Date calculations
• api-error-handling.ts - API error utilities
• user-validation.ts - User input validation

Why this matters:

• Discoverability: Developers find code by scanning file names
• Cohesion: Related code stays together
• Prevents bloat: Hard to add unrelated code to string-formatting.ts
• Import clarity: import { formatDate } from './date-arithmetic' is self-documenting

When you're tempted to create utils.ts: Stop. Ask what the functions have in common. Name the file after that commonality.

Module Organization

• Keep module boundaries strict with restricted visibility
• Platform-specific code in separate files: unix.ts, windows.ts, posix.ts
• Use conditional compilation or runtime checks for platform branching
• Test helpers in dedicated modules/files, not mixed with production code

Cross-Platform Principles

Use OS-Native Logic

Don't emulate Unix on Windows or vice versa. Use each platform's native patterns.

Bad: Trying to make Windows paths behave like Unix paths everywhere.

Good: Accept platform differences, handle them explicitly.

// Platform-specific behavior
if (process.platform === 'win32') {
  // Windows-native approach
} else {
  // POSIX approach
}

Platform-Specific Files

When platform differences are significant, use separate files:

process-spawn.ts        // Shared interface and logic
process-spawn-unix.ts   // Unix-specific implementation
process-spawn-windows.ts // Windows-specific implementation

Document Platform Differences

When behavior differs by platform, document it in comments:

// On Windows, this returns CRLF line endings.
// On Unix, this returns LF line endings.
// Callers should normalize if consistent output is needed.
function readTextFile(path: string): string { ... }

Test on All Target Platforms

Don't assume Unix behavior works on Windows. Test explicitly:

• CI should run on all supported platforms
• Platform-specific code paths need platform-specific tests
• Document which platforms are supported

Common Mistakes

Red Flags

Stop and refactor when you see:

• A utils.ts or helpers.ts file growing beyond 200 lines
• Error handling that swallows errors or uses generic messages
• Platform-specific code mixed with cross-platform code
• Abstractions created for single use cases
• Type assertions (as any) to bypass the type system
• Code that "works on my machine" but isn't tested cross-platform

Commit Hygiene

Applies to all languages. Commits are the unit of review and bisect; treat them with the same care as the code they contain.

• Each commit is a logical, atomic unit of change.
• Every commit must build and pass all checks (bisect-able history).
• Separate concerns: formatting fixes and refactoring go in separate commits from feature changes.
• Use simple past and present tense in bodies: "Previously X happened. With this commit, Y now happens."
• Commit message bodies use markdown. Do not use backticks in commit titles, but do use them in bodies.