top-down-typescript
TypeScript and JavaScript coding style conventions, centered on top-down narrative ordering (caller first, helpers below) and functions over classes. Read before writing or reviewing TypeScript/JavaScript code, including code inside a spec or a plan.
paleo · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add paleo/alignfirst --skill top-down-typescript技能说明
name: top-down-typescript description: TypeScript and JavaScript coding style conventions, centered on top-down narrative ordering (caller first, helpers below) and functions over classes. Read before writing or reviewing TypeScript/JavaScript code, including code inside a spec or a plan. license: CC0 1.0 metadata: author: Paleo version: "0.4.0" repository: https://github.com/paleo/skills
Top-Down TypeScript Coding Style
General Rules
- Dead (unused) code SHOULD NOT be kept (YAGNI principle).
- Do not write multiple consecutive blank lines.
- Changes to linter rules MUST be discussed before being implemented.
- Code SHOULD NOT contain commented-out code, unless a comment explains why.
Code Organization
Usage comes first, implementation after. Exception: with inheritance — when an interface extends another, write the parent first.
-
Order code top-down: each file reads as a story, from entry point to leaves. The reader meets the highest-level thing first, then drills down into its dependencies:
// 1. Imports import { ... } from "..."; // 2. Module-level constants and variables (exported first, then internal) export const PUBLIC_CONST = ...; const INTERNAL_CONST = ...; // 3. Shared types — main type first, then types it references export interface MainType { detail: DetailType; } export interface DetailType { ... } // 4. Entry-point (exported) function export function doThing() { stepOne(); stepTwo(); } // 5. Internal functions called by the entry point, in call order function stepOne() { stepOneHelper(); } function stepOneHelper() { ... } function stepTwo() { ... } -
Module-level constants and variables (
const,let,varvalue declarations at the top of the file — both exported and internal) MUST be placed immediately after imports, before any type definitions, functions, or classes. The reader sees them first and treats them as the file's configuration surface. -
Functions: write the caller first, then the functions it calls, recursively. A helper appears just below its caller, not grouped at the bottom of the file. If a helper is called by several siblings, place it after its first caller.
-
Types: write the main (top-level) type first, then the types it references, recursively. Same top-down rule as functions.
-
Types attached to a single function (or class, or other declaration) — i.e. used only in that one signature, like a
MyComponentPropsinterface used only byMyComponent— must be placed immediately before that declaration, not in the top type block. -
Exports are not a sorting criterion on their own: a
functionbeingexported does not pull it to the top — its position is determined by who calls it. The entry points of a file are usually exported, which is why they tend to appear first, but that is a consequence of the top-down rule, not the rule itself.
Code Quality Standards
- Strive for elegant solutions from the first implementation
- Avoid redundant operations, especially expensive ones like image conversion
- Avoid duplicated code and logic
- Pass previously calculated values between functions instead of recalculating
- Use early returns to simplify code flow when possible
- For code that leaves the current flow (
throw,return,continue,break), when it fits on one line, write it on one line (e.g.,if (!condition) return false;instead of multi-line format) - Use function and variable names that clearly convey intent, reducing the need for comments
- Keep functions small with a single responsibility
- Avoid
any; take the time to find the proper type. If you fail to find one, always insert a/* FIXME */after theany. For example:let myVariable: any /* FIXME */;. - Export only functions (or variables, classes) that are imported from elsewhere. By default, do not export.
- When an interface is used in the signature of an exported function or component, that interface must also be exported.
Imports
- Always use ESM import syntax (e.g.,
import { X } from "y.js"instead ofrequire). - Avoid circular imports between modules.
TypeScript, JavaScript
- Never use
enumandnamespace. - Prefer
constoverlet. - Prefer
undefinedovernull. - Prefer
??over||. - Prefer
++iand--ioveri++andi--. - Prefer
new Error()overError(). - At the top level, prefer the
functionandclassdeclarative syntax over creating them as constants. - Keep an empty line between top-level functions, classes, interfaces.
- Implementation of a getter or setter (EcmaScript 5 syntax) must never throw exceptions.
- Prefer
interfacedeclarations overtypealiases. - Prefer a single capital letter for generics parameters, such as
T,K, etc. - Do not differentiate between an absent property and a property with an
undefinedvalue. - Use camelCase for string literal values in TypeScript union types (e.g.,
"normal" | "gracefulShutdown" | "backupMode"instead of"normal" | "graceful-shutdown" | "backup-mode"). - Never use an empty string as a default value unless you really mean an empty string. If a variable might not have a value, use
undefinedor throw an error if the absence of value indicates a problem. - The existence of string, number, boolean values (and identifiers when they are string or number) must NEVER be tested by coercing to boolean. Use explicit comparisons with
undefinedornull. - Existence checks for objects and arrays MAY use boolean coercion.
- Never explicitly assign or return
undefinedwhen it is the default value. Usereturn;instead ofreturn undefined;andlet myVariable;instead oflet myVariable = undefined;. Explicitly passingundefinedis fine when intentionally setting a value. - Avoid
as anyor any kind of type assertion. Always make the effort to find the proper type. Exception: when the type is incorrect or truly unknown — justify with an inline comment. - Nev