Files
kotosoft-id/CODE_STYLE_PROFILE.md
T
2026-05-04 11:14:30 +03:00

3.9 KiB

Code Style Profile (Go + JSX/Next.js)

This document captures your current coding style as seen in the repository and lists questions to refine your preferred style rules.

Go Style (Observed)

What is consistent

  • Clear layered architecture: handlers -> services -> repositories.
  • Short, readable functions with early returns over deep nesting.
  • Explicit request/response DTO structs in handlers with Gin binding tags.
  • Business logic mostly lives in services, SQL mostly in repositories.
  • Error mapping style is pragmatic (models.ErrBadRequest, ErrForbidden, etc.).
  • Naming is mostly clear and domain-driven (AssignPosition, RecordUserConsent, GetUserPositions).

Style characteristics

  • You prefer practical over abstract code (few interfaces beyond service boundaries).
  • You accept some inline structs for one-off request payloads.
  • You keep SQL as raw strings in repository methods (not hidden behind ORM abstractions).
  • You usually avoid over-commenting; code is expected to be self-explanatory.
  • You follow gofmt defaults and avoid stylistic tricks.

JSX / Next.js Style (Observed)

What is consistent

  • Functional components with hooks (useState, useForm, useTranslations).
  • Strong TypeScript typing for props and form data.
  • UI composition via reusable primitives (Dialog, Table, Button, custom fields).
  • Local optimistic state updates after server actions.
  • Short handlers with readable names (handleCreated, handleUpdated, handleDelete).
  • Frequent early exits on failure (if (!result.success) { ... return }).

Style characteristics

  • You favor compact code and inlined JSX in places where intent is obvious.
  • You rely on server actions for API calls and keep transport details in actions/*.
  • You use translation keys heavily (good i18n discipline).
  • You keep component files focused on one domain workflow.

Your Answers (Captured)

Go

  • Error philosophy: undecided for now.
  • Strict types over any: undecided for now.
  • Authorization model: should be based on explicit permissions; admin role is a temporary service mechanism.
  • Zero affected rows on update/delete: return not_found by default.
  • SQL approach: keep inline raw SQL in this project.

JSX / Next.js

  • Component formatting: compact by default; multiline only when complexity justifies it.
  • Mutation strategy today: optimistic updates currently used.
  • Validation style: prefer schema-based validation over ad-hoc inline checks.

Pending Clarifications

  1. Optimistic vs refetch default (Q7):
    Recommendation: keep optimistic update as default for snappy UX, and use refetch for high-risk operations (complex server-side side effects, computed fields, permission-dependent payloads).

  2. Display naming policy (Q8, clarified):
    Proposed rule: in UI, show user-facing label first (name or description) and fallback to code only when label is empty.
    Please confirm if you want this as a global rule.

Final Summary (Current)

Confirmed style rules

  • Go authorization should move toward explicit permissions, not role-only checks.
  • Go repositories should return not_found for update/delete when 0 rows affected.
  • Go SQL stays inline/raw in this project.
  • JSX/Next components should be compact by default; multiline formatting is allowed when readability needs it.
  • Frontend validation direction is schema-first.
  • Mutation UX: optimistic updates by default; refetch only for risky mutations with possible server-side divergence.
  • Action results: migrate from bare { success } to richer result objects:
    • success path: { success: true, data?: T }
    • error path: { success: false, errorCode: string, message?: string }

Still open

  • Go error-wrapping strictness (fmt.Errorf("...: %w", err) everywhere vs selective).
  • Strict ban of any in all service/repository boundaries.
  • Global UI naming fallback rule (name/description first, code as fallback).