Global Best Practices

Priority: P0 (FOUNDATIONAL)

🏗 SOLID & Architectural Principles

• SRP (Single Responsibility): One class/function = One reason to change. Separate business logic from delivery (UI/API).
• OCP (Open-Closed): Extended via composition/interfaces; closed to source modification.
• LSP (Liskov): Subtypes must be transparently replaceable for base types. Use @override carefully.
• ISP (Interface Segregation): Granular interfaces > "Fat" general-purpose ones.
• DIP (Dependency Inversion): Depend on abstractions (interfaces), not concretions. Use DI containers.
• Modular Design: Break complex systems into small, independent, and swappable components to reduce cognitive load.

🧹 Clean Code Standards (KISS/DRY/YAGNI)

• KISS: Favor readable, simple logic over "clever" one-liners.
• DRY: Abstract repeated logic into reusable utilities. No magic numbers/strings.
• YAGNI: Implement only current requirements. Avoid "just in case" abstractions.
• Meaningful Names: Use intention-revealing names (isUserAuthenticated > checkUser).
• Naming Conventions: Follow language-specific standards:
  • camelCase: Variables/Functions (JS/Java/Dart).
  • snake_case: Variables/Functions (Python/Ruby).
  • PascalCase: Classes/Types (universal).
  • kebab-case: Files/CSS/URLs.
• Function Size: Keep functions small (target < 20 lines) and single-responsibility.
• Guard Clauses: Prefer early returns to avoid deep nesting (Pyramid of Doom).
• Comments: Explain why, not what. Refactor unclear code before commenting.

🛡 Security & Performance Foundations

• Sanitization: Always validate external input (API, User, Env) to prevent Injection/XSS.
• Early Return: Guard clauses first to minimize nesting and improve readability.
• Lazy Loading: Defer heavy initialization or data fetching until actually needed.
• Resource Cleanup: Always close streams, file handles, and database connections to prevent leaks.

🧱 Error Handling

• Predictable Failures: Use custom exception types over generic Catch-Alls.
• Graceful Degradation: Fallback values/UI for non-critical failures.
• Log Context: Log actionable metadata (ID, State) along with errors. Avoid silent failures.

♻️ Safe Refactoring Workflow

• Tests First: Run tests before refactors; keep changes atomic.
• Find Usages: Locate all call sites before renaming or moving code.
• Layer Moves: Business logic belongs in Domain/Application, not UI.
• Commit Often: Prefer small, reviewable refactors over large rewrites.

🚫 Anti-Patterns

• Magic Numbers: **No Hardcoded Constants**: Use named constants or config.
• Pyramid of Doom: **No Deep Nesting**: Use guard clauses and early returns.
• Mutable Globals: **No Global State**: Use dependency injection or state management.
• Silent Failures: **No Empty Catch**: Always handle, log, or rethrow errors.

📚 References

• Code Structure & Modular Design Examples
• Skill Token Economy & Effectiveness