AyCode.Core/docs/CONVENTIONS.md

Conventions

Naming

• Prefix: All framework types use Ac prefix (e.g., AcDalBase, AcBinarySerializer, AcLoggerBase).
• Interfaces: Standard I prefix + Ac (e.g., IAcDbContextBase, IAcUserDbSetBase).
• Extensions: {Domain}Extensions.cs (e.g., StringExtensions, CollectionExtensions, AcDbSessionExtension).
• Test bases: Ac{Domain}TestBase or AcBase_{TestName} for inherited test methods.

Patterns

• Extension methods over instance methods for CRUD operations. Keeps interfaces clean, implementations composable.
• Session/Transaction pattern in DataLayers: Session() for reads, Transaction() for writes. Both are mutex-protected.
• Generic interface hierarchy for entities: Interface → Abstract Entity → Concrete (in consuming project).
• Partial classes for large serializers (AcBinarySerializer, AcToonSerializer split across 10+ files).
• Source generation for hot-path serialization. Runtime reflection only as fallback.

Serialization Conventions

• Binary serializer properties are written in alphabetical order (matches source generator output).
• String interning is opt-in via [AcStringIntern] attribute or enableInternString flag.
• Chain API for multi-type deserialization with cross-reference resolution.
• Feature flags on [AcBinarySerializable] eliminate dead code from generated output.

Testing

• MSTest framework across all test projects.
• Abstract test bases with AcBase_ prefixed methods for reusable test logic.
• TestDataFactory for centralized test data creation with ID sequencing.
• Testable infrastructure for SignalR: TestableSignalRClient2, TestableSignalRHub2 bypass real connections.

Code Reuse

• Before writing new code, search the codebase for existing implementations.
• If a method does most of what you need, extract the shared part into a smaller reusable method rather than copying and modifying.
• Prefer composing existing helpers over creating parallel implementations.
• When adding a variation of existing logic, refactor the original into composable pieces that both call sites can use.

Critical Rules

• Never modify PasswordHasher salt/iteration logic — breaks existing password verification.
• Never renumber LogLevel enum values — synchronized with database.
• Never fix "Finnished" spelling — intentional legacy typo in consuming projects.
• Never suggest removal as a solution — find a fix instead.