Typescript

Writing TypeScript

You write TypeScript code that is clear, predictable, and easy to maintain. The goal is to make the codebase safer, more understandable, and easier to refactor without over-engineering.

Principles

• Type safety over flexibility.
• Clarity over cleverness.
• Type inference where it makes sense.

General Guidelines

• Prefer type over interface.
• Explicit return types for functions.
• Avoid any. Use unknown when the type is unclear.
• Prefer primitive types over complex ones unless necessary.
• Use readonly when possible.
• Avoid enums. Use string literal unions instead.
• Always use const instead of let.
• Use satisfies instead of as
• Always use arrow functions when possible

Naming Conventions

• Be descriptive.
• Use suffixes appropriately.

Working with Vue + TypeScript

• Explicitly type defineProps and defineEmits.
• Explicit return types for composables.
• Explicitly type Ref and ComputedRef.

Testing

• Write all tests using vitest.
• Ensure you cover all main cases as well as edge cases, try to break the code with the tests.
• Create the test file alongside the file being tested, call it name.test.ts.

Great Comments for All Types

• Use comments to explain why, not what. Most of the time, the code explains what is happening. Comments should clarify why a type or function exists, why you made specific decisions, or why a workaround is necessary.
• Write friendly comments that sound human. Comments should be clear and helpful, not robotic or overly formal. Aim for a tone that's friendly and supportive, like you're helping a teammate understand the code later.

Good:

/**
 * We load the user here to make sure we have fresh data when the component mounts.
 * Without this, the user info could be stale.
 */

Bad:

/**
 * Load user.
 */

• Avoid contractions in comments. Use do not instead of don't, it is instead of it's, etc. This makes comments easier to read, especially for non-native speakers.

• If you use contractions, make sure they have proper apostrophes. Sometimes contractions can make a comment more approachable. If you choose to use them, use proper punctuation.

• Comment on types when their purpose isn't obvious. If a type models an external API, or has a non-obvious constraint, explain it.

• Explain relationships between types when they're not clear.

Example:

/**
 * Maps UserStatus to a badge color used in the UI.
 * Should stay in sync with the theme color palette.
 */
export type StatusColorMap = {
  active: 'green'
  inactive: 'gray'
}

• Document the intent of utility types or generic types.

Example:

/**
 * Represents a partial object where at least one property is required.
 * Useful when you want to enforce at least one field update in a PATCH request.
 */
export type AtLeastOne<T> = {
  [K in keyof T]: Partial<T> & Pick<T, K>
}[keyof T]

• For complex function signatures or composables, describe the behavior and usage.

Example:

/**
 * useUser composable for loading and managing user data.
 * Fetches the user from the API and exposes reactive state.
 *
 * Returns:
 * - user: Ref<User | null>
 * - isLoading: Ref<boolean>
 * - loadUser: Function to manually trigger user loading
 */
export function useUser() { ... }

• If the type is temporary or will change later, leave a TODO comment.

Example:

/**
 * TODO: Replace with dynamic permissions from backend when available.
 */
export type Permissions = 'read' | 'write' | 'admin'

• Use JSDoc style consistently for types and functions that are exported or public. This improves editor support (tooltips, autocompletion) and helps other developers understand your code faster.

Example

/**
 * A user in the system.
 * This type represents the internal data structure for application logic.
 * If you need to expose user data publicly, use `PublicUser`.
 */
export type User = {
  /** Unique identifier for the user (UUID). */
  id: string
  /** The user's full name. */
  name: string
  /** Email address. Must be validated before saving. */
  email: string
  /** ISO date string of when the user signed up. */
  createdAt: string
  /** Whether the user has verified their email. */
  isVerified: boolean
}

Converted and distributed by TomeVault — claim your Tome and manage your conversions.