CTC Code Simplification Guideline Review¶

Classification: RESEARCH-INPUT
Captured: 2026-08-11
Source baseline: kylejang1/ctc qa@0979513b69f5ea01100c37b98b41dd7757945991
Question: whether the proposed short-function, low-call-count, higher-level-code, maintainability, AI-comprehensibility and performance direction is technically sound and what additional rules should be integrated
Durable decision owner: Context Appendix R
Primary Task owner: P5-001
Method: official standard/guideline review plus current CTC source/task comparison
Mutation summary: documentation only; no Runtime, DB, provider, Wiki, service, deployment or Phase effect
Limitations: no complete repository AST/caller manifest, Local Runtime profile, DB/browser evidence or Production performance measurement in this review

1. Executive Finding¶

The user's direction is sound when treated as a review and prioritization model, not as automatic deletion thresholds.

The strongest supported formulation is:

short function
+ low verified fan-in
= review metadata

short function
+ low verified fan-in
+ pass-through/alias/trivial same-owner transformation
+ no distinct semantic or boundary contract
+ no public/dynamic/external/compatibility/test consumer
= redundant-indirection candidate

The review also supports four additions:

narrow scope/public exposure before considering deletion;
classify why dead code exists before removal;
distinguish semantic duplication from merely similar syntax;
require task-based AI reconstruction and measured performance rather than function/file counts.

2. Source Quality And Selection¶

The review prioritized primary and recognized engineering sources.

Source	Authority used	Relevant conclusion
ISO/IEC 25010:2023	international product-quality model	quality is multi-characteristic and should be specified, measured and evaluated; one source metric is insufficient
C++ Core Guidelines	broadly adopted language/design guideline led by Bjarne Stroustrup	package meaningful operations, one logical operation per function, keep functions short/simple; small functions can be legitimate
Google Engineering Practices — code review	large-scale industrial review practice	review system design and complexity, avoid over-engineering/speculative generality, consider the whole file/system and keep style churn separate
Google Engineering Practices — small changes	large-scale industrial change discipline	one self-contained change is easier to review, reason about and roll back; unused APIs should not be introduced
SEI CERT DCL19-C	secure coding standard	variables/functions should use the minimum scope that still supports all references
SEI CERT MSC07-C / MSC12 relationship	secure coding standard	dead code often indicates a logic/environment change; understand and correct the cause before elimination
Microsoft Framework Design Guidelines — abstractions	public framework API design guidance	excessive abstractions reduce usability; abstractions should be validated by actual implementations and consuming APIs
PHPStan unused method	PHP static-analysis documentation	unused private methods are safely bounded dead code because external reachability is impossible
PHPStan always-used methods	PHP static-analysis extension guidance	reflection/framework mechanisms can produce false positives and require explicit handling
PHP-FIG PSR-12	PHP syntax/style convention	useful for presentation consistency only; it does not determine architecture, necessity or performance

The C++ and C references are not copied as PHP rules. They are used for general design reasoning and adapted to CTC's global functions, includes, public routes, browser callbacks and legacy compatibility model.

3. Assessment Of The Original Heuristics¶

3.1 Two or three lines or fewer¶

Finding: reasonable as inventory metadata, not as a smell or automatic action.

A very small function may still own:

a domain predicate;
an authorization or tenant boundary;
a transaction/effect transition;
a public route/callback;
a provider adapter;
compatibility;
stable result/error mapping;
a test seam.

Recommended interpretation:

executable statement count <= 3
= short_body metadata

Physical lines are rejected because formatting can change without changing behavior.

3.2 Fewer than two calls¶

Finding: useful primarily for consumer and exposure review.

A one-call function may still execute repeatedly in a loop, act as a route/callback, or preserve a public compatibility name. A no-static-call function may be reached by reflection, include, browser event, scheduler, webhook or external URL.

3.3 Higher-level code¶

Finding: sound, provided it means intent-bearing code rather than more wrappers.

Preferred trace:

adapter
-> application command/query
-> process/domain policy
-> repository/transaction/effect adapter
-> authoritative readback

A layer that only renames and forwards inputs/results is not higher-level unless it preserves a real contract.

3.4 Performance maximization¶

Finding: must remain measurement-owned.

Reducing functions, files or hops may help comprehension, but it does not prove faster Runtime behavior. CTC's likely dominant costs include DB queries, schema probes, session locking, route/include loading, filesystem operations, provider/network calls, serialization and browser polling. Function-call overhead belongs later in the measurement order unless profiling shows otherwise.

4. Additional Rules Required¶

4.1 Minimum scope and exposure¶

For every low-fan-in symbol record current and minimum exposure.

GLOBAL
PUBLIC
ROUTE
CALLBACK
MODULE_INTERNAL
CLASS_PRIVATE
LOCAL

Possible outcome:

necessary symbol
+ unnecessarily broad exposure
= NARROW_SCOPE_CANDIDATE

4.2 Abstraction admission¶

Every abstraction must name the distinct contract it adds, current consumer, owner, compatibility/test value and removal condition. Generic architecture vocabulary is not sufficient evidence.

4.3 Dead-code cause¶

Before deletion classify whether the cause is stale implementation, superseded compatibility, accidental early return, incomplete migration, disabled feature, logic defect, rollback path or unknown.

4.4 Semantic duplication¶

Similar syntax is merged only when business meaning, owner, lifecycle, error/recovery, transaction/effect and reason to change are the same.

4.5 Test sensitivity¶

A characterization test should observe a public result or authoritative readback and fail when the preserved behavior is intentionally broken. Source-string presence alone is not behavior evidence.

4.6 Style separation¶

Formatting, broad renaming and PSR-12 cleanup should not be mixed with query, transaction, compatibility or dead-code retirement waves because they obscure review and rollback.

5. CTC Source/Task Fit¶

Current CTC planning already separates most responsibilities correctly:

P5-001 inventory
-> P5-002 public/internal contract
-> P5-003 command/query/repository/transaction/effect templates
-> P5-005 reference conversion
-> P5-006 bounded waves and caller-zero

Adjacent owners remain:

P4 for execution context and tenant/profile/config authority;
P6 for process/state/retry/recovery meaning;
P7 for browser/global/plugin/shell lifecycle;
P9 for measured performance;
P12 for later React + Next.js migration.

The current P5-001 specification already contains useful symbol, dynamic-caller, semantic-boundary, AI-reconstruction and performance-handoff sections. The material correction is that short + low-call alone must not be described as a high-priority cleanup signal.

6. Recommended Document Integration¶

Context¶

Appendix R records the durable interpretation and explicitly corrects P5-001's earlier shorthand.

P5-002¶

Add minimum exposure, abstraction admission, public-surface justification and compatibility-retirement requirements.

P5-003¶

Require every layer to add a distinct contract; allow named local operations; reject forwarding-only architecture; use one logical operation rather than a physical length limit.

P5-006¶

Add scope narrowing, dead-code cause, semantic-duplication proof, test sensitivity and style-only separation before retirement.

P7-005¶

Account for browser/dynamic caller mechanisms before frontend function/global/plugin deletion.

P9-003¶

Explicitly prohibit function/file/LOC/wrapper/static-call counts as performance KPIs and require equivalent-scenario profiler-supported before/after evidence.

7. Current Effect And Evidence State¶

external guideline review: COMPLETE
user direction fit: SUPPORTED WITH CORRECTION
Context decision: owned by Appendix R
Task specification updates: documentation package
complete repository symbol inventory: NOT RUN
complete dynamic/external caller accounting: NOT RUN
Local Runtime profiling: NOT RUN
DB/browser/target-role evidence: NOT RUN
source cleanup/deletion: NOT AUTHORIZED / NOT RUN
Phase progress: NONE

This research record is not an implementation or performance result. Future execution must repin current source and use the applicable Work Graph, caller, restriction, rollback and verification contracts.

---¶

Source: docs/research/code-quality/2026-08-11/CTC_CODE_SIMPLIFICATION_GUIDELINE_REVIEW.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.