# Coding Standards

> Cross-language coding standards for Python, TypeScript, and Go covering naming, SOLID design, code smell removal, and comment philosophy. Use when writing, reviewing, or refactoring production code for maintainability. Use when this capability is needed.

- Skill: `tomevault-io/coding-standards-15` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/coding-standards-15`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/coding-standards-15/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/coding-standards-15

---


# Coding Standards

Write code that is obvious to change: clear names, small units, stable abstractions, and comments that explain intent rather than syntax.

## When to Activate

- Rename ambiguous identifiers
- Split oversized functions or modules
- Introduce a new abstraction or interface
- Review a pull request for maintainability drift
- Add comments around non-obvious behavior
- Remove dead code after a feature change
- Port logic between Python, TypeScript, and Go

## Naming

| Language | Types | Functions | Variables | Constants |
| --- | --- | --- | --- | --- |
| Python | `PascalCase` | `snake_case` | `snake_case` | `UPPER_SNAKE_CASE` |
| TypeScript | `PascalCase` | `camelCase` | `camelCase` | `UPPER_SNAKE_CASE` for module constants |
| Go | `PascalCase` exported, `camelCase` internal | `camelCase` | `camelCase` | `PascalCase` or `camelCase` scoped to package |

Rules:

- Prefer names that reveal domain meaning, not implementation detail.
- Boolean names should read as predicates: `is_active`, `hasAccess`, `canRetry`.
- File names should match the dominant abstraction.

## SOLID Without Ceremony

| Principle | Apply As | Avoid |
| --- | --- | --- |
| Single Responsibility | One unit changes for one reason | Utility files collecting unrelated behavior |
| Open/Closed | Extend via composition, interfaces, data-driven config | Switch chains duplicated across modules |
| Liskov | Keep subtype behavior substitutable | Hidden preconditions in implementations |
| Interface Segregation | Small focused interfaces | God interfaces with optional methods |
| Dependency Inversion | Depend on abstractions at boundaries | Concrete infrastructure leaking into business logic |

Python

```python
class PriceCalculator:
    def total(self, items: list[LineItem]) -> Decimal:
        return sum((item.total for item in items), start=Decimal("0"))
```

TypeScript

```ts
export interface PaymentGateway {
  charge(input: ChargeInput): Promise<ChargeResult>;
}
```

## Code Smells

| Smell | Signal | Refactor |
| --- | --- | --- |
| Long function | More than one phase or branching matrix | Extract helpers by intent |
| Primitive obsession | Raw strings for domain identifiers | Introduce value objects or typed aliases |
| Shotgun surgery | One rule changed in many files | Centralize policy |
| Boolean parameter explosion | `doThing(x, true, false, true)` | Split commands or use typed options |
| Dead code | Unreachable branches, unused exports | Delete it |

## Comment Philosophy

| Write Comments For | Do Not Comment |
| --- | --- |
| Non-obvious constraints | Syntax the reader can already see |
| External protocol quirks | Temporary debugging leftovers |
| Performance tradeoffs | Repeating function names in prose |
| Security-sensitive assumptions | Commented-out dead code |

BAD

```python
def normalize_email(email: str) -> str:
    # Lowercase the email
    return email.lower()
```

GOOD

```python
def normalize_email(email: str) -> str:
    # Login matching is case-insensitive across legacy providers.
    return email.strip().lower()
```

BAD

```ts
function handle(user: any, flag1: boolean, flag2: boolean) {
  if (flag1) {
    // ...
  }
}
```

GOOD

```ts
type HandleMode = "create" | "update";

interface HandleOptions {
  mode: HandleMode;
  sendNotification: boolean;
}

function handleUser(user: UserInput, options: HandleOptions) {
  if (options.mode === "create") {
    // ...
  }
}
```

## No Speculative Abstractions

| Situation | Preferred | Avoid |
| --- | --- | --- |
| Unused helper after refactor | Delete it in the same change | Leave for "future use" |
| One implementation today | Concrete type with clean seam | Factory + interface + registry on day one |
| Feature flag fully rolled out | Remove flag path | Carry stale branches indefinitely |

## Checklist

- [ ] Names encode domain meaning and read naturally
- [ ] Each function has one clear job
- [ ] Abstractions solve a present need, not a hypothetical one
- [ ] Comments explain why a constraint exists
- [ ] Unused code and commented-out blocks are removed
- [ ] Boolean argument lists are replaced with clearer APIs where needed
- [ ] Cross-module dependencies flow inward toward business logic
- [ ] Examples and tests still compile after refactors

---
> Source: [kid-sid/codex-spellbook](https://github.com/kid-sid/codex-spellbook) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-15 -->