Mas Code Standards

MAS Code Standards

Objective

Reproduce the practical implementation style used in current dev without copying obsolete behavior or broadening scope unnecessarily.

Scope

Primary style reference samples:

1. frontend/electron/services
2. frontend/electron/ipc
3. frontend/src/views/Initialization

Use these samples as style lenses only. For frontend engineering or UI decisions, prefer mas-frontend-standards and mas-frontend-ui; for Python modules, carry over the same values of explicit orchestration, compatibility-first changes, and operational logging, but always compare nearby files before applying style assumptions.

Workflow

1. Read references/style-observations.md, with priority on commit lenses e541fa5f, 727aafb, and e5d72bdb.
2. Sample 2 to 3 sibling files in the same module before editing.
3. Keep the main execution path obvious; extract helpers only when they make the flow easier to follow.
4. Match nearby naming, logging tone, comment style, and result contracts.
5. Prefer minimal edits that blend into surrounding code rather than style-driven rewrites.
6. If recent maintainer review comments are available for the same area, treat them as the strongest style signal.
7. Before completing a user-visible feature or fix, add exactly one changelog fragment under changelog.d/ (<PR number or branch>.<feat|change|fix|breaking|remove|security|dev>.md; first line project: <key> from the project table in changelog.d/README.md — 14 adapters plus home / scheduler / emulator / notify / tools / settings / update / runtime, no catch-all, pick the nearest per the README; only dev fragments may omit it; then one user-facing sentence of at most 50 characters without project prefix, PR number or signature; python scripts/changelog.py add <type> <project> "<sentence>" creates it, with - as the project for dev). Before writing a fix or change fragment, decide which release introduced the feature you touch: a feature absent from the previous stable release's notes was introduced in the current X.Y.0 cycle (for 5.5.0: Runtime initialization, virtual display, Emulator 2.0, MFW, BetterGI, BAAH, ZZZ-OD, config restore, operator cultivation). Every later fix, maintenance or supplementary change to such a feature (bug fixes, turning something into a prompt, extra hints, default tweaks, layout changes, i18n wiring, cleanup) is beta-only: if the feature's entry is still in the top ## [未发布] section or its fragment is still in changelog.d/, add no fragment and label the PR skip-changelog (describe any wording change in the PR for a maintainer to apply); if it shipped in an earlier beta of the cycle, add the header line beta-only: true so the entry is dropped from the stable roll-up. Sub-features added to it later are beta-only as well: in the stable notes a new adapter is exactly one line (【bgi】新增 bgi 专项) and a new feature is its single introduction entry; fixes and changes to features that shipped in the previous stable are normal. Project keys use the short names bgi (BetterGI) and end (MaaEnd). A PR with several human authors lists them all in the header line author: a, b (the script never reads Co-authored-by). Maintainers may add highlight: true to route an entry into 「本次亮点」; treat it as part of the implementation rather than a reminder. Condense all changes of the PR into that one sentence. Never edit CHANGELOG.md, res/version.json or any version number: they are written only by the release PR.

Commit Lenses

1. e541fa5f: small cleanup. Keep logic local, remove one-off indirection, simplify conditions without changing outcome.
2. 727aafb: feature landing. Extend existing books, models, managers, routes, forms, and logs in parallel instead of inventing a separate architecture for the new type.
3. e5d72bdb: dev integration. Preserve the feature branch structure, then consolidate at integration points instead of rewriting during merge.

Core Traits

1. Use clear file sections such as // ==================== 类型定义 ====================.
2. Keep module headers and comments short, Chinese, and purpose-driven.
3. Prefer explicit orchestration over generic abstractions or clever helpers.
4. Use getLogger('中文名') and short operational log lines.
5. Allow light duplication when it keeps each step readable and local.
6. Respect file-local formatting; do not normalize unrelated code.
7. When adding a new script or domain type, extend config model, schema, routing, task registration, frontend types, composables, and edit views together.
8. Prefer compatibility edits at registration points such as BOOK, union types, routing branches, and progress payloads before deeper refactors.
9. For finite variants, prefer a small dict/registry mapping instead of many near-identical branches.
10. Keep frequently edited task-configuration logic visible in the owning flow with a short comment instead of hiding it behind one-off helpers.
11. Do not copy another script/domain's special-case logs, timeout exemptions, ignore lists, or workaround branches into a new module until that behavior is confirmed locally.
12. If a new capability is used only once, default to an inline block or local helper; split into builder, loader, or extra services only after real reuse or boundary pressure appears.
13. Trust existing validators, config containers, and task bases when they already guarantee an invariant; do not add a second layer of fallback or correction.
14. For new Python-heavy flows, keep signatures and call sites compatible with at least basic static type checking.
15. Prefer deleting redundant imports, waits, and wrappers over preserving "explicit" but noisy scaffolding.
16. Use Conventional Commits for commit messages: <type>(<scope>): <subject>, with documented types such as feat, fix, docs, style, refactor, perf, test, chore, build, and ci.
17. Choose commit scope from the touched file name when one file changes, or from the parent folder name when multiple related files change.
18. For backend docstrings, use Google-style sections for summary, Args, Returns, and Raises when a function needs explanation.
19. For ConfigBase subclasses, comment every ConfigItem and group config items by clear section markers before super().__init__().