oop-dev-skill

This skill encodes universal engineering standards for object-oriented software. When applied, Claude enforces these rules across any OOP language — the principles are language-agnostic unless a specific rule maps naturally to the target language's idioms.

The user may ask for code review, generation, refactoring, architecture design, test writing, or database schema design. Apply whichever sections are relevant.

---

1. Naming Conventions#

Hard Rules (enforce always)#

• No leading/trailing underscores or special symbols in public identifiers. Names like _name, name_, $obj are forbidden.

• No mixing of local language phonetics with a foreign language in the same identifier. Use either full English or full native language — never a hybrid like getUserPingfen().

• Class names: Use UpperCamelCase. Exception: well-known domain abbreviations (e.g. DTO, VO, BO) may retain their canonical form.

  • Good: UserAccount, OrderService, XmlParser
  • Bad: userAccount, XMLparser, order_service

• Methods, parameters, local variables: Use lowerCamelCase.

  • Good: getUserById, localValue, inputUserId

• Constants: All uppercase with underscore separators. Prefer full descriptive names.

  • Good: MAX_RETRY_COUNT, DEFAULT_TIMEOUT_SECONDS
  • Bad: MAX, TIMEOUT

• Abstract classes: Prefix with Abstract or Base.

• Exception classes: Suffix with Exception (e.g. PaymentException).

• Test classes: Named after the class under test, suffixed with Test (e.g. OrderServiceTest).

• Boolean fields in data objects: Do NOT prefix with is. Many serialization frameworks will misread isDeleted as field deleted, causing runtime failures.

  • Good: deleted, active, enabled
  • Bad: isDeleted, isActive

• Packages/modules: All lowercase, single semantic word per segment, singular form.

• No opaque abbreviations: condi for condition, abs for abstract — forbidden. Names must be self-explanatory.

Recommended#

• Encode design patterns in names when applicable: OrderFactory, LoginProxy, ResourceObserver.
• Interface capability names: Use adjective form where natural (e.g. Translatable, Serializable, Configurable).
• Service/DAO implementation classes: Suffix with Impl to distinguish from the interface (e.g. UserServiceImpl implements UserService).
• Enums: Suffix with Enum; members are all-uppercase with underscores (e.g. OrderStatusEnum.PENDING_PAYMENT).

Layer Naming Conventions#

LayerMethod prefix conventionDAO/Repositoryget (single), list (multiple), count, save/ insert, remove/ delete, updateDomain modelsXxxDO (data object), XxxDTO (transfer), XxxVO (view), XxxBO (business)

---

2. Constants and Magic Values#

• No magic values — never embed unexplained literals directly in logic.

  • Bad: cache.put("Id#order_" + orderId, value)
  • Good: define ORDER_CACHE_KEY_PREFIX = "Id#order_" as a named constant

• Long/integer literals: Use uppercase suffix where the language requires it (e.g. 2L not 2l; 2.0f not 2.0F ambiguously).

• Split constants by concern — do not create one monolithic Constants class. Group into CacheConstants, SecurityConstants, ConfigConstants, etc.

• Constant scoping levels (from broadest to narrowest): cross-application shared → application-wide → module-level → package-level → class-private.

• Use enums for named value sets — especially when values carry semantic meaning beyond their raw type (e.g. days of week, order statuses).

---

3. Code Formatting#

• Brace style: Opening brace on the same line as the statement; closing brace on its own line. Empty bodies may be written as {} inline.

• Indentation: 4 spaces. Never use tabs (or configure tabs as 4 spaces if the language convention mandates them).

• Spaces around operators: All binary and ternary operators must have one space on each side ( =, &&, +, etc.).

• No space between a function/method name and its opening parenthesis. No space after ( or before ).

• Reserved words ( if, for, while, switch) require a space before the opening parenthesis.

• Line length limit: 120 characters. When wrapping:

  • Indent the second line by 4 spaces; subsequent continuation lines stay at the same indent as line 2.
  • Break after commas; break before method-chaining dots.
  • Never break immediately before an opening parenthesis.

• Comment spacing: One space between the comment marker and content ( // comment, # comment).

• File encoding: UTF-8. Line endings: Unix ( LF).

• Blank lines: One blank line between logically distinct blocks within a method. No need for multiple blank lines as separators.

---

4. OOP Principles#

Hard Rules#

• Access statics via class name, not via an instance reference.

• Always annotate overridden methods (e.g. @Override in Java/Kotlin, explicit override keyword in others). This surfaces signature mismatches at compile time.

• Wrapper/boxed types for data object fields — primitive defaults can mask missing data (a 0 looks like valid data; null clearly signals "not set"). Use primitives only for local variables where performance matters.

• Data objects (DTOs, POJOs, etc.): Do not assign default values to fields at declaration. Defaults hide missing assignments and cause subtle bugs.

• No business logic in constructors. Use an explicit init() or factory method.

• All data objects must implement a human-readable string representation ( __repr__, toString, etc.) for easier debugging.

• Restrict access as tightly as possible:

  • Private constructors for utility/singleton classes.
  • Private fields unless subclass sharing is intentional.
  • Private methods unless they form part of an inheritance contract.

Recommended#

• Validate split() / split-like results before index access — trailing delimiters yield fewer elements than expected.
• Group related constructors and overloads together in the class body.
• Class member ordering: public/protected methods → private methods → getters/setters.
• No logic in getters/setters — these must be pure accessors.
• String concatenation inside loops: Use a mutable buffer ( StringBuilder, list join, etc.) — never += string in a loop body.
• Use final/ const/ val liberally: for classes not meant to be subclassed, for fields that must not be reassigned, for local variables that should not change.
• Be cautious with shallow clone/copy — if your language's default copy is shallow, explicitly implement deep copy when needed.

---

5. Collection Handling#

• Always override both equality and hash together when using objects as map keys or set members.
• Do not cast sub-list / sub-collection views to their parent collection type — they are views, not independent copies.
• Modifying the original collection while a view (subList, etc.) is live throws a concurrent modification error. Avoid.
• When converting arrays to resizable collections, use the proper API that yields a fully mutable collection — not a fixed-size adapter.
• Do not mutate (add/remove/clear) adapter-backed collections returned by utilities like Arrays.asList() or equivalent — they are fixed-size adapters.
• Producer/Consumer generics (where applicable): read-heavy → use upper-bounded type; write-heavy → use lower-bounded type.
• Never remove/add during a for-each loop — use an explicit iterator and call iterator.remove().
• Comparator contracts: When implementing comparison, handle the equal case explicitly. Comparators that only return 1 or -1 (never 0) violate contract and cause sort instability.
• Pre-size collections when the final count is known. For hash maps: capacity = (expected_count / load_factor) + 1.
• Iterate maps with entry-set (key+value in one pass), not key-set (two lookups per entry).
• Know your collection's null policy: Some concurrent/sorted implementations reject null keys or values outright. Do not assume HashMap/dict behavior universally.

---

6. Concurrency#

• Singleton objects and their methods must be thread-safe.
• Name all threads/thread-pools with meaningful identifiers for traceback in production.
• Never create raw threads outside a pool. Always use a managed executor/thread pool.
• Size your thread pools explicitly — avoid framework defaults that allow unbounded queues or unbounded thread counts (both cause OOM).
• Date/time formatters are not thread-safe in most languages. Do not share a single formatter instance across threads. Use thread-local storage or the language's thread-safe alternatives.
• Lock granularity: prefer lock-free structures → fine-grained locks → coarse locks. Minimize code inside locked sections. Never make remote calls inside a lock.
• Consistent lock ordering across all code paths to prevent deadlock (if thread A locks X then Y, thread B must never lock Y then X).
• Concurrent record updates: use optimistic locking (version field) when conflict probability < 20%; otherwise use pessimistic locking. Retry at least 3 times on optimistic lock failure.
• Scheduled task runners: use robust executor implementations that isolate task failures — one failing task must not silently kill sibling tasks.
• Double-checked locking: the target field must be declared volatile (or equivalent) to prevent CPU/compiler reordering.
• Atomic counters: for simple increment/decrement shared counters, use atomic integer types rather than synchronized blocks.
• Thread-local state: mark thread-local variables as static; they are per-thread, not per-instance.

---

7. Control Flow#

• switch statements: every case must either break/ return or have an explicit fall-through comment. Always include a default branch, placed last.

• Always use braces for if/ else/ for/ while/ do — even single-line bodies.

• Minimize if-else nesting — prefer early return / guard clauses over deeply nested branches. Max 3 levels of nesting; beyond that, refactor with guard clauses, strategy pattern, or state pattern.

• Extract complex conditions into a well-named boolean variable before the if. Inline complex boolean expressions hurt readability.

• Move invariants out of loops: object creation, DB connection acquisition, and avoidable try-catch blocks should live outside loop bodies.

• Validate batch API inputs — enforce upper bounds on input sizes to prevent memory exhaustion.

• Parameter validation rules:

  • Validate at: low-frequency methods, expensive operations, high-stability requirements, all public/RPC/HTTP entry points, permission gates.
  • Skip validation at: hot inner-loop methods (document the contract instead), deeply internal private methods with confirmed-safe callers.

---

8. Comments and Documentation#

• Class-level, field-level, and method-level documentation must use the language's structured doc format (docstring, Javadoc, JSDoc, etc.) — not inline // comments.

• All abstract methods / interface methods require doc comments explaining purpose, parameters, return values, exceptions, and any implementation constraints.

• Every class must record its author and creation date.

• Inline comments go on the line above the code they describe, not at the end of the line.

• All enum members must have comments explaining their purpose.

• Prefer clear native language comments over broken English — domain terms and keywords stay in English; explanations can be in the team's working language.

• Keep comments in sync with code — stale comments are worse than no comments.

• Do not comment out dead code silently — either delete it (version control preserves history) or leave a clear explanation above it with TODO/ FIXME markers.

• Annotation markers:

  • TODO(author, date) — functionality not yet implemented.
  • FIXME(author, date) — known broken code needing urgent fix.

• Comment quality target: comments should convey why and business meaning, not restate what the code does. Self-explanatory code needs no comment.

---

9. Exception Handling#

• Prevent exceptions via pre-checks where possible — do not use exceptions as flow control.

• Catch narrow exception types — avoid blanket catch(Exception) except at application boundaries.

• Never swallow exceptions silently — either handle them or re-throw. An empty catch block is always wrong.

• Transaction rollback: if an exception occurs inside a transaction, explicitly trigger rollback — don't rely on implicit behavior.

• Always close resources in finally blocks (or use language-level resource management: with, try-with-resources, using, RAII, etc.).

• Never return from a finally block — it silently swallows exceptions from the try block.

• Caught exception type must match or be a parent of the thrown exception type.

• NPE / null-safety discipline:

  • Return values may be null — document when and protect callers.
  • Unbox wrapper types only after null-check.
  • Guard against null from: DB queries, remote calls, session data, chained calls.
  • Prefer optional/maybe types where the language supports them.

• Error propagation strategy:

  • HTTP/public APIs: return structured error codes + messages.
  • Internal application logic: throw typed exceptions.
  • Cross-service RPC: return a result wrapper with isSuccess(), error code, and error message.

• DRY principle: extract repeated validation or error-handling logic into shared private methods or base classes.

---

10. Logging#

• Use an abstraction layer (logging facade/interface) — do not bind directly to a specific logging library. This makes the implementation swappable.

• Log retention: keep at least 15 days of logs (weekly-pattern anomalies require this window).

• Log file naming convention: {appName}_{logType}_{description}.log — e.g. orderservice_monitor_paymentTimeout.log.

• Guard log statements at debug/ trace level to avoid string interpolation cost when the level is inactive: text

  if logger.is_debug_enabled():
      logger.debug(f"Processing order {order_id}")
  
  

  Or use lazy interpolation syntax provided by the logging framework.

• Prevent duplicate log propagation — configure appenders to avoid the same log entry appearing multiple times.

• Exception log entries must include: context parameters AND the full stack trace.

• Production log level discipline: no debug in production; info selectively; warn for recoverable anomalies; error for genuine system faults only.

---

11. Unit Testing#

Hard Rules (AIR Principles)#

• Automatic — tests run fully without human intervention. No print/console assertions — use framework assertions only.
• Independent — test cases must not call each other or depend on execution order.
• Repeatable — tests must produce identical results regardless of environment, time, or external state. Inject or mock all external dependencies (DB, network, filesystem, time).
• Granularity: one test = one method or one behavior. Tests do not verify cross-class interaction (that is integration testing).
• All new code in critical paths must have passing unit tests before merging.
• Test code lives in the designated test directory (e.g. src/test/, tests/), never in the production source tree.

Recommended (BCDE Principles)#

• Border — test boundary values: loop edges, empty collections, max/min values, date boundaries.
• Correct — test the happy path with valid inputs and verify expected output.
• Design — derive test cases from the design specification, not just from the implementation.
• Error — test with invalid inputs, illegal states, and exception paths.

Additional recommendations:

• Code coverage target: 70%+ statement coverage overall; 100% branch + statement coverage for core modules.
• Use programmatic data setup, not manually inserted DB rows — hand-inserted data often violates business rules and makes tests fragile.
• Database-touching tests should auto-rollback or use clearly prefixed test data.
• Refactor untestable code (excessive globals, deep external dependencies, complex constructors) rather than writing workarounds.

---

12. Database Design (SQL / Relational)#

Table Structure#

• Boolean/flag fields: named is_xxx, type unsigned tiny integer (0/1). All non-negative numeric fields must be unsigned.
• Table and column names: lowercase letters and digits only. No uppercase, no leading digits, no double-underscore-with-digit patterns (e.g. level_3_name is bad; level3_name is acceptable).
• Table names: singular noun (e.g. user, order_item — not users).
• Reserved words: never use DB-reserved words as identifiers.
• Index naming: pk_ prefix for primary keys; uk_ for unique indexes; idx_ for regular indexes.
• Decimal precision: use DECIMAL/ NUMERIC — never FLOAT/ DOUBLE for stored values that require exact comparison.
• Variable-length strings: use variable-length type up to a reasonable limit (e.g. 5000 chars). Beyond that, store in a separate text-type column in its own table linked by primary key.
• Mandatory audit columns on every table: id (unsigned bigint, auto-increment primary key), gmt_create (datetime), gmt_modified (datetime).
• Table naming: {business_domain}_{entity_role} (e.g. payment_task, trade_config).
• Split tables only when a single table exceeds 5 million rows or 2 GB — not preemptively.

Index Design#

• Unique constraints for business-unique fields — even composite uniqueness should be enforced at DB level, not just application level.
• No more than 3-table JOINs in a single query. All joined columns must have matching types and indexes.
• Partial indexes on long string columns — index a prefix of sufficient cardinality, not the full column.
• No left-side or full wildcard pattern matching in queries intended to use indexes (e.g. LIKE '%value%' defeats the index). Route full-text search to a search engine.
• Composite index column order: highest-cardinality / equality-condition columns first; range-condition columns last.
• Covering indexes: design indexes that satisfy a query's projection without a table lookup.
• Pagination on large offsets: use keyset pagination (seek method) or a subquery to locate the ID range before fetching rows.
• SQL optimization target levels (best to worst): constant lookup → ref (index) → range → full scan. Avoid full scans.

SQL Statements#

• Never use SELECT * — always name columns explicitly.
• COUNT(*) is the standard row count; COUNT(col) skips NULLs. Use accordingly.
• NULL comparisons: use IS NULL / IS NOT NULL or the equivalent function — direct equality comparison with NULL always yields NULL, not true/false.
• Skip the pagination query entirely when the count is 0 — avoid executing the offset query unnecessarily.
• No database-level foreign key constraints or cascades in high-concurrency distributed systems — enforce referential integrity in the application layer.
• No stored procedures — they are opaque, hard to test, and non-portable.
• Before any DELETE or UPDATE: run a SELECT first to verify the target rows, then execute the mutation.
• IN lists: keep under 1000 elements.
• Character encoding: use UTF-8 universally. Use UTF-8 MB4 (or equivalent) when emoji/4-byte characters must be stored.

ORM Mapping#

• Always define explicit result mappings — never use dynamic hash maps as query result types.
• Use parameterized queries exclusively — string-interpolated SQL is a SQL injection vector.
• Update only changed fields — do not emit an update for every field on every save. This avoids errors, reduces load, and keeps audit logs clean.
• Always update gmt_modified when writing a record.
• Avoid overly broad update interfaces that blindly write every field regardless of what changed.

---

13. Application Layering#

Recommended layer hierarchy (each layer depends only on layers below it):

text

[ Open API / Gateway Layer ]   [ Frontend / Template Layer ]
              ↓
       [ Web / Controller Layer ]
              ↓
       [ Service Layer ]
              ↓
       [ Manager Layer ]
              ↓
       [ DAO / Repository Layer ]
              ↓
       [ Data Source / External APIs ]

Layer responsibilities:

• Open API: Expose service methods as RPC/HTTP; handle auth, rate limiting, input validation.
• Web/Controller: Route requests, basic parameter validation, no complex business logic.
• Service: Core business logic.
• Manager: Cross-cutting concerns — caching, middleware integration, orchestrating multiple DAOs.
• DAO/Repository: Data access only. No business logic.

Exception handling by layer:

• DAO: catch broadly, wrap in a typed data-access exception, do not log (Service will log).
• Service: catch and log with context. This is the primary error recording boundary.
• Web/Controller: never propagate exceptions upward past the boundary — convert to user-friendly error responses.
• API Gateway: convert all exceptions to structured error code + message responses.

Domain model types:

TypeMeaningDO / EntityMaps 1:1 to a DB table rowDTOData transferred between service boundariesBOEncapsulates business logic outputVOData shaped for the view/UI layerQuery objectEncapsulates query parameters (2+ params → object, not map)

---

14. Dependency and Build Management#

• Version format: MAJOR.MINOR.PATCH — start at 1.0.0. Major = breaking change; Minor = backward-compatible features; Patch = bug fixes.
• No SNAPSHOT/pre-release dependencies in production builds.
• When adding or upgrading a dependency, verify that transitive dependency versions have not silently shifted. Audit and lock the full dependency tree.
• Enums in shared libraries: safe to use in parameters; do not use as return types across service boundaries (deserialization failures on version skew).
• Unified version variables for dependency groups (e.g. all modules of the same framework should reference a single version variable).
• No duplicate groupId + artifactId with different versions within the same build graph.

---

15. Server / Runtime Configuration#

• TCP TIME_WAIT timeout: reduce from OS default (often 240 s) to ~30 s on high-concurrency servers to avoid connection exhaustion.
• File descriptor limits: increase the OS limit well above the default (often 1024) to accommodate concurrent connections.
• Heap dump on OOM: configure the runtime to emit a heap dump on out-of-memory events — these are rare and the dump is invaluable for diagnosis.
• Heap min == heap max: set initial and maximum heap sizes to the same value in production to eliminate GC-triggered heap resize pauses.
• Internal redirects: use server-side forwarding. External redirects must use a URL-building utility — never hand-concatenate redirect URLs.