Codewriter Skill

Code Writer Expert

Overview

Advanced expertise in writing clean, production-ready, idiomatic code across multiple languages and paradigms. Specialized in designing well-structured functions, classes, modules, and systems with a focus on correctness, readability, testability, performance, and security.

Use this skill with /codewriter-skill to get expert code writing, refactoring, design, or generation for any language or framework.

1. Code Writing Principles

• Clarity first: code is read far more than it is written — optimize for the reader
• Single Responsibility: each function/class does one thing and does it well
• DRY (Don't Repeat Yourself): extract duplication into named abstractions
• YAGNI: only write code that is needed now — no speculative generality
• Fail fast: validate inputs early, surface errors explicitly, never swallow exceptions
• Minimal surface area: expose only what callers need, keep internals private
• Immutability preference: prefer immutable data structures and pure functions
• Explicit over implicit: readable names, clear types, no magic numbers/strings

2. Naming Conventions

3. Function Design

• Keep functions short: aim for < 20 lines; if longer, extract sub-functions
• Max 3 parameters: beyond that, use an options object/struct/dataclass
• No side effects in pure functions: separate computation from I/O
• Early returns: reduce nesting by returning/throwing early on invalid conditions
• Guard clauses: validate preconditions at the top before main logic
• One level of abstraction per function: don't mix high-level orchestration with low-level details
• Command-Query Separation: functions either do something OR return something, not both
• Avoid flag parameters: split into two functions instead of doThing(flag: bool)

# Bad
def process(data, dry_run=False):
    result = compute(data)
    if not dry_run:
        save(result)
    return result

# Good
def compute_result(data): ...
def save_result(result): ...

4. Class & Module Design

• SOLID principles:
  • S — Single Responsibility
  • O — Open/Closed (extend via composition, not modification)
  • L — Liskov Substitution (subtypes are substitutable)
  • I — Interface Segregation (small, focused interfaces)
  • D — Dependency Inversion (depend on abstractions)
• Composition over inheritance: prefer has-a over is-a relationships
• Dependency injection: pass dependencies in; don't instantiate them inside
• Factory functions/classes: encapsulate complex construction logic
• Repository pattern: abstract data access behind an interface
• Service layer: encapsulate business logic separately from controllers/routes

5. Error Handling

• Never swallow errors silently: always log or re-raise
• Use domain errors: define typed error classes (not just Error("something failed"))
• Result types: use Result<T, E> or Either patterns for expected failures
• Exception vs error return: exceptions for unexpected failures; return errors for expected ones
• Error messages: include what went wrong, where, and what the caller can do

// TypeScript Result pattern
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

function parseId(raw: string): Result<number, string> {
  const n = parseInt(raw, 10);
  if (isNaN(n)) return { ok: false, error: `Invalid ID: "${raw}"` };
  return { ok: true, value: n };
}

6. Language-Specific Best Practices

TypeScript / JavaScript

• Strict mode: "strict": true in tsconfig
• Prefer const → let → never var
• Optional chaining ?. and nullish coalescing ?? over explicit null checks
• async/await over raw Promises and callback chains
• Use unknown over any; narrow types explicitly
• Zod / Valibot for runtime validation at boundaries

Python

• Type annotations on all public functions/methods
• Dataclasses or Pydantic models over plain dicts
• pathlib.Path over os.path string manipulation
• Context managers for resource management
• __slots__ for performance-critical classes
• logging module over print statements

Go

• Errors as values: always handle err != nil
• Interfaces implicitly satisfied — keep them small (1-3 methods)
• Goroutines + channels for concurrency; use context.Context for cancellation
• defer for cleanup, not just error handling
• Table-driven tests with t.Run

Rust

• Ownership and borrowing — prefer references over clones
• Result<T, E> and Option<T> over panics at boundaries
• thiserror for library errors, anyhow for application errors
• Iterators over manual loops
• #[derive(Debug, Clone, PartialEq)] on data structs

Java / Kotlin

• Immutable data with record (Java 16+) or data class (Kotlin)
• Builder pattern for objects with many optional fields
• Optional<T> for nullable return values (Java); ? types (Kotlin)
• Stream API / sequences for collection processing
• Constructor injection for dependencies

7. Code Structure Patterns

Repository Pattern

interface UserRepository {
  findById(id: string): Promise<User | null>;
  save(user: User): Promise<void>;
  delete(id: string): Promise<void>;
}

class PostgresUserRepository implements UserRepository { ... }
class InMemoryUserRepository implements UserRepository { ... } // for tests

Service Layer

class OrderService:
    def __init__(self, orders: OrderRepository, payments: PaymentGateway):
        self._orders = orders
        self._payments = payments

    def place_order(self, cart: Cart, payment: PaymentDetails) -> Order:
        order = Order.from_cart(cart)
        self._payments.charge(payment, order.total)
        self._orders.save(order)
        return order

Builder Pattern

class QueryBuilder {
  private _table = "";
  private _conditions: string[] = [];
  private _limit?: number;

  table(name: string) { this._table = name; return this; }
  where(condition: string) { this._conditions.push(condition); return this; }
  limit(n: number) { this._limit = n; return this; }
  build(): string { ... }
}

8. Testing-Friendly Code

• Dependency injection: makes unit testing easy — swap real deps for mocks
• Pure functions: no mocking needed — input → output is deterministic
• Small functions: easy to test in isolation
• Avoid global state: global mutable state makes tests order-dependent
• Interfaces at boundaries: mock at interface boundaries, not concrete implementations
• Seams: design code to have natural injection points for test doubles
• Test naming: <unit>_<scenario>_<expected> — e.g., login_with_wrong_password_returns_401

9. Performance-Aware Code Writing

• Avoid premature optimization — profile first, optimize after
• Prefer O(n) over O(n²) by using sets/maps for lookups
• Lazy evaluation: generators, iterators, streams over eagerly-loaded collections
• Batch DB queries instead of N+1 loops
• Cache pure function results with memoization
• Avoid allocations in hot paths (object pooling, pre-allocated buffers)
• Use streaming for large file/data processing

10. Security-Aware Code Writing

• Input validation: validate at every system boundary — never trust external data
• Parameterized queries: never concatenate user input into SQL
• Output encoding: escape HTML/JS output to prevent XSS
• Secrets in env vars: never hardcode tokens, passwords, or keys
• Least privilege: request only the permissions your code actually needs
• Safe deserialization: validate schemas before unmarshalling untrusted JSON/YAML
• Path traversal prevention: sanitize file paths; use allowlists
• Timing-safe comparisons: use constant-time comparison for secrets/tokens

11. Code Review Checklist

• Does the code do what the ticket/spec says?
• Are edge cases handled (empty, null, large input, concurrency)?
• Are errors handled and surfaced appropriately?
• Are names descriptive and consistent with existing conventions?
• Is there unnecessary complexity or duplication?
• Are there tests, and do they cover the important paths?
• Are there any security issues (injection, exposure, auth bypass)?
• Does it perform acceptably under expected load?
• Are public APIs documented?
• Are there any TODO/FIXME that should be issues instead?

12. Refactoring Techniques

• Extract Function: pull repeated or complex logic into a named function
• Inline Function: remove unnecessary indirection when function body is self-evident
• Extract Variable: name complex expressions for readability
• Replace Magic Number: introduce a named constant
• Introduce Parameter Object: group related parameters into a struct/object
• Replace Conditional with Polymorphism: use strategy/factory instead of large if/switch
• Decompose Conditional: extract complex boolean logic into named predicate functions
• Replace Temp with Query: replace variables computed once with functions

Core Competency Summary

• Write clean, idiomatic, production-ready code in Python, TypeScript, Go, Rust, Java, and more
• Design functions, classes, and modules following SOLID principles
• Apply naming conventions, error handling, and guard clause patterns consistently
• Structure code for testability via dependency injection and pure functions
• Write security-aware code at every boundary
• Recognize and apply structural patterns: Repository, Service, Builder, Strategy
• Perform disciplined refactoring using established techniques
• Write code that passes review: correct, clear, tested, and performant