# Human-Centric Code Style ## 1. Core Principle AI MUST NOT write code that merely looks impressive. AI MUST write code that an experienced human developer would be comfortable maintaining six months later. Prefer: ```text Simple Clear Predictable Intentional Maintainable ``` over: ```text Clever Over-engineered Over-abstracted Verbose Artificially sophisticated ``` --- # 2. Existing Project Style Comes First Before writing new code: - Inspect nearby code. - Follow established naming. - Follow existing folder conventions. - Follow existing response conventions. - Follow existing exception patterns. - Follow existing architectural patterns. Do not introduce a completely different coding style into one module. --- # 3. Prefer Simple Code If two implementations are functionally equivalent, prefer the one that is easier for another developer to understand. Do not use complex patterns merely to demonstrate architectural knowledge. --- # 4. Avoid AI-Generated Overengineering Do NOT create unnecessary: - Helpers - Utilities - Wrappers - Factories - Managers - Coordinators - Strategies - Adapters - DTOs - Value Objects - Traits - Base classes - Generic abstractions unless they solve a real problem. --- # 5. Abstraction Rule Use: > "Abstract because there is a reason, not because abstraction is possible." Good reasons include: - Reuse - Replaceability - Clear architectural boundary - Complex behavior - Domain concept - Testability Do not create an abstraction for one trivial operation merely to make the architecture appear sophisticated. --- # 6. Naming Names MUST communicate intent. Prefer: ```text createContract() approveContract() calculateCommission() assignTeamMember() changeContractStatus() ``` Avoid vague names: ```text process() handle() execute() manage() run() doWork() ``` unless their meaning is genuinely clear from the class context. --- # 7. Business-Oriented Naming Use domain language. Prefer: ```text calculateCommission() ``` over: ```text calculateAmount() ``` Prefer: ```text approveContract() ``` over: ```text updateStatus() ``` when the operation specifically represents approval. The code should communicate business intent. --- # 8. Method Size Methods SHOULD have one clear responsibility. Avoid methods that simultaneously: - Validate input - Query multiple domains - Calculate business values - Persist data - Send notifications - Format API responses Break responsibilities only when doing so improves clarity. Do not split every three lines into another method. --- # 9. Comments Comments should explain WHY, not WHAT. Bad: ```php // Get the user $user = User::find($id); ``` Good: ```php // The contract owner must remain unchanged after approval. ``` Use comments for: - Business constraints - Compatibility reasons - Non-obvious decisions - Workarounds - Important architectural decisions Do not comment obvious code. --- # 10. Avoid AI Commentary Do not generate comments such as: ```text // This function is used to... // Here we create the user... // Now we check if... // This loop iterates through... ``` These comments add noise. --- # 11. Avoid Excessive Defensive Programming Do not add null checks, fallback values, exception handling, or validation merely because "something might happen." Understand the project's actual contracts first. Defensive programming should address realistic failure scenarios. --- # 12. Avoid Clever One-Liners Do not sacrifice readability for fewer lines. Prefer explicit code when business logic becomes difficult to understand. --- # 13. Avoid Deep Nesting Prefer: - Guard clauses - Early returns - Clear conditions when they improve readability. Avoid deeply nested: ```text if if if if ``` structures. --- # 14. Laravel Pragmatism Prefer Laravel's native capabilities when they provide a clean solution. Examples: - Form Requests - Policies - Resources - Events - Jobs - Notifications - Validation - Eloquent relationships - Scopes - Queues - Cache Do not rebuild Laravel features without a project-specific reason. --- # 15. Do Not Create a Mini Framework The application is not improved by creating: ```text GenericBaseService GenericBaseRepository GenericCrudManager UniversalProcessor UniversalHandler GenericResponseFactory ``` unless there is a proven project-wide requirement. --- # 16. Consistency Over Personal Preference When modifying existing code, follow the project's established convention even if another style would personally be preferred. Do not perform stylistic rewrites unrelated to the task. --- # 17. Explicitness For important business logic, prefer explicit code. A future developer should be able to understand: - What is happening - Why it is happening - What conditions control it - What data is being changed without mentally executing a chain of abstractions. --- # 18. Error Handling Errors should be meaningful. Avoid generic catches that hide the real problem. Do not swallow exceptions. Bad: ```php try { ... } catch (Throwable $e) { return null; } ``` unless this behavior is explicitly intended and documented. --- # 19. Reuse Existing Code Before creating a new helper, service, method, or utility: Search for an existing implementation. Prefer reuse when the existing implementation has the same business meaning. Do not create duplicate implementations. --- # 20. Don't Mix Refactoring With Features When implementing a feature, do not rewrite unrelated existing code simply because it could be cleaner. If refactoring is valuable, report it separately. --- # 21. Human Review Test Before finalizing code, ask: ```text Would an experienced developer understand this code immediately? Would they understand why the abstraction exists? Would they be comfortable modifying it six months from now? Does anything look unnecessarily generated or over-engineered? ``` If the answer is no, simplify the implementation. --- # 22. Final Principle Write code as if: > Another experienced developer will maintain it without the AI being available. The code must stand on its own.