code

This document outlines a comprehensive set of instructions for coding agents, derived from a thorough analysis of best practices in software development. The goal is to ensure the generation of high-quality, reliable, maintainable, scalable, and secure code. Each instruction is self-contained, providing sufficient detail for immediate application without external references.

The core principle here is to ensure that domain objects are always in a valid state, both upon creation and throughout their lifecycle. This prevents the creation of invalid objects and shifts the responsibility of validation from the calling side to the domain object itself. This approach is fundamental to maintaining business consistency and is achieved by designing with types, eliminating "loose" types that can hold anything, and addressing implicit relationships between multiple attributes. Key Points: • Validation within Constructor: Prevent invalid objects from being created by enforcing validation rules in the constructor. • Design with Types: Use specific types to represent business rules and valid states, especially for atomic attributes and related state transitions. This also relates to Type-First Development (TFD). • Separate Validated States: For attributes with state-dependent validity (e.g., verified email), define distinct types for each state (e.g., UnverifiedEmailAddress and VerifiedEmailAddress). Sample Code/Configuration: `java // BEFORE: Validation logic is external and can be forgotten. public class RegisterMemberUseCase { private SaveMemberPort saverMemberPort; void register(RegisterMemberCommand command) { if (!command.getEmailAddress().matches("^\\S+@\\S+\\.\\S+$")) { // Easily forgotten throw new IllegalArgumentException(); } Member member = new Member(command.getEmailAddress()); saveMemberPort.save(member); } } // AFTER: Validation is encapsulated within the Member constructor, ensuring Always-Valid state. // This is the preferred approach for Always-Valid Domain Models. @Getter public class Member { String emailAddress; public Member(String emailAddress) { if (!emailAddress.matches("^\\S+@\\S+\\.\\S+$")) { throw new IllegalArgumentException("Invalid email address format."); } this.emailAddress = emailAddress; } // No isValid() method as the object is always valid by design. } // Example of designing with types for state-dependent validity. // EmailAddress as an abstract base type. @Getter public abstract class EmailAddress { String value; // Constructor to set the value EmailAddress(String value) { this.value = value; } } // VerifiedEmailAddress can only be created via a verification process. public class VerifiedEmailAddress extends EmailAddress { VerifiedEmailAddress(String value) { super(value); // Additional logic for verification success could be here, or enforced by the service. } } // UnverifiedEmailAddress represents an unverified state. public class UnverifiedEmailAddress extends EmailAddress { public UnverifiedEmailAddress(String value) { super(value); } } // Services interact with specific types, enforcing business rules at the type level. public interface VerifyEmailService { VerifiedEmailAddress verify(UnverifiedEmailAddress emailAddress); } public interface SendNotificationService { void send(VerifiedEmailAddress emailAddress); // Only verified emails can receive notifications } // Member class uses the EmailAddress abstraction. public class Member { EmailAddress emailAddress; // Constructor and other methods would ensure the correct EmailAddress type is used. } `

Adhering to robust architectural principles is crucial for building maintainable, scalable, and flexible systems. Key Points: • Clean Architecture: Design systems where the core business logic (domain model) is independent of external details like databases, UIs, and frameworks. This promotes testability and flexibility. • Dependency Inversion Principle (DIP) and Dependency Injection (DI): Depend on abstractions, not concrete implementations. DI enables loose coupling, making systems more flexible, testable, and maintainable. • Humble Object Pattern: Separate behaviors that are hard to test from those that are easy to test. The "humble" part (e.g., UI, database access) is minimal and hard to test, while the testable logic is extracted. • Microservices: Consider breaking down large systems into smaller, independently deployable services, being mindful of the complexities introduced (e.g., distributed transactions, data consistency). Sample Code/Configuration: `java // Clean Architecture / DIP Example (Conceptual) // Core Domain Interface (Abstraction) public interface MemberRepository { void save(Member member); Member findById(MemberId id); } // Application Service (depends on abstraction) public class RegisterMemberApplicationService { private final MemberRepository memberRepository; // Depends on interface public RegisterMemberApplicationService(MemberRepository memberRepository) { this.memberRepository = memberRepository; } public void register(RegisterMemberCommand command) { // Business logic Member member = new Member(command.getEmailAddress()); // Always-Valid domain object memberRepository.save(member); } } // Infrastructure Implementation (Concrete) public class JpaMemberRepository implements MemberRepository { // JPA specific implementation @Override public void save(Member member) { // Save to database } @Override public Member findById(MemberId id) { // Fetch from database return null; // Placeholder } } // Dependency Injection (Conceptual using a DI container) // In a framework like Spring or Guice, this would be configured. // For example, using a Simple Injector like approach: // var container = new Container(); // container.Register<IMemberRepository, JpaMemberRepository>(); // container.Register<RegisterMemberApplicationService>(); // // Registering a specific type for an abstraction // services.AddTransient<IMemberRepository, JpaMemberRepository>(); // Humble Object Pattern (Conceptual for a UI) // Untestable UI component (Humble Object) public interface MemberView { void displayMember(MemberDto member); String getEmailInput(); } // Testable Presenter public class MemberPresenter { private MemberView view; private MemberApplicationService service; public MemberPresenter(MemberView view, MemberApplicationService service) { this.view = view; this.service = service; } public void onRegisterClicked() { String email = view.getEmailInput(); try { service.register(new RegisterMemberCommand(email)); view.displaySuccessMessage("Member registered!"); } catch (IllegalArgumentException e) { view.displayErrorMessage("Invalid email format."); } } } `

Clean code is paramount for readability, maintainability, and collaboration. Key Points: • Meaningful Names: Use names that clearly convey intent and context. Avoid abbreviations or generic terms unless universally understood. • Small Functions/Methods: Keep functions small and focused on a single responsibility. This improves readability and testability. • Comments: Use comments sparingly and only when code cannot express its intent. Avoid redundant, misleading, or too much historical information. @Ignore for long tests is a good use case. • Error Handling: Use exceptions for truly exceptional conditions and define them in terms of the caller's needs. Prefer returning result objects (e.g., Either, Result) for expected failure paths, especially in functional styles. Avoid returning or passing null. • Immutability: Favor immutable objects, especially for Value Objects, to ensure their state cannot be changed after creation. This simplifies reasoning about the code and reduces side effects. • Concurrency: Handle concurrency explicitly and carefully, being aware of potential issues like race conditions and deadlocks. Use appropriate synchronization mechanisms. For Go, GOMAXPROCS can control CPU usage. Sample Code/Configuration: `java // Error Handling: Using a Result type for expected outcomes // Instead of throwing an InsufficientFundsException, return a Result. public final class Account { private long balance; // Assume Amount is a Value Object here public Result transfer(final Amount amount, final Account toAccount) { // Validation using utility (example) // notNull(amount); // notNull(toAccount); if (balance().isLessThan(amount)) { return Result.failure(FailureType.INSUFFICIENT_FUNDS); // Expected failure path } return executeTransfer(amount, toAccount); // Returns Result.success() } private Result executeTransfer(Amount amount, Account toAccount) { // Actual transfer logic this.balance -= amount.getValue(); toAccount.balance += amount.getValue(); return Result.success(); } public Amount balance() { return new Amount(this.balance); } } // Result.java (simplified) public class Result { private final FailureType failure; private final boolean isSuccess; private Result(boolean isSuccess, FailureType failure) { this.isSuccess = isSuccess; this.failure = failure; } public static Result success() { return new Res