General Programming Guidelines

These rules apply to all programming projects regardless of language.

IMPORTANT: After each task, check for useless code

After finishing any task, look through your changes and see if any useless code was left there. Remove any redundancies.

IMPORTANT: Expected behavior and gotchas comments

When implementing behavior-sensitive code, add a brief comment block near the top of the file/class that captures:

  • Expected behavior: what should happen in normal use
  • Gotchas: pitfalls, framework constraints, or edge cases that can cause regressions

Keep it short and practical. When a new bug or trap is discovered, add/update the Gotchas comment in that code.

IMPORTANT: Inventing UI

If user asks for a feature, but doesn’t specify what the UI should look like, first think about the UI. Come up with the idea and present it to user with ASCII chart of the proposed UI. Wait for user’s confirmation.

IMPORTANT: Image optimization

When adding images to any project (iOS, web, etc.), always resize and optimize them for their intended use case before committing:

  • Resize to match the display context (e.g., 2x the intended CSS/point size for retina, no larger)
  • Compress using available tools (pngquant for PNG, sips for resizing, jpegoptim/cjpeg for JPEG)
  • Never commit the raw full-resolution source image when a smaller version suffices

Boolean naming

All booleans should be prefixed with is-, was-, wants-, has- and similar prefixes. This applies to booleans in code and in database fields.

For example, use wantsAutoUpdate instead of autoUpdate.

Return Type Clarity

For method return values that represent operation outcomes or states, prefer enums over booleans.

Use booleans only for predicate-style methods where true/false is self-evident from the method name (for example isValid(), hasAccess(), wantsSync()).

Method Grouping

In any class with multiple methods, organize them into logical groups. Each group gets a comment header: first line is the group name, second line is a full-width dash separator.

Lifecycle should always be the first group. It contains the constructor/initializer and the main public entry point(s) (e.g. call, run, perform).

After Lifecycle, group the remaining private/helper methods by concern. Choose group names that describe what the methods do together. Order groups to match the execution flow — groups used earlier in the entry point come first, groups used later come last.

Method Ordering

Within each group (and in general), place entry point / public methods first and helper / private methods last. A reader should see the high-level flow before the implementation details.

Variable Naming

Avoid acronym or abbreviated variable names. Use descriptive names that make the code readable without context. For example, use const config = userData.reflectConfig ?? {} instead of const rc = userData.reflectConfig ?? {}.

Naming Stability (No Convenience Renames)

Do not rename a variable, field, or interface key just to avoid a local conflict or make one place easier to code.

Treat this as a code smell. If names collide, refactor structure instead (separate DTO/domain models, introduce clearer boundaries, rename computed/display properties).

Rename only when meaning actually changes. If data is persisted or shared across APIs, do a full rename across layers with backward compatibility or migration.

Examples:

  • Bad (Swift): rename stored field to titleText only because model already has computed title.

  • Better (Swift): keep persisted field name stable (for example title) and rename the computed/display property (for example displayTitle) or split storage/domain models.

  • Bad (TypeScript): backend writes aiTitle while clients still read title only to avoid a local naming conflict.

  • Better (TypeScript): keep canonical contract keys stable and resolve local conflicts by refactoring types/functions; if contract key must change, migrate and support both keys during transition.

  • Bad (Any language): local aliases like userIdValue, memoTitleText, statusStringValue when original names were changed only for convenience.

  • Better (Any language): preserve canonical names; fix the design that causes ambiguity instead of patching names locally.