Skip to content

PROPOSED_README.md

Latest commit

 

History

History
146 lines (109 loc) · 7.46 KB

PROPOSED_README.md

File metadata and controls

146 lines (109 loc) · 7.46 KB

DevCore Software Design Principles Handbook

Build Status Code Coverage Tech Stack License GitHub Stars

A definitive handbook for crafting clean, scalable, and maintainable code through essential software engineering principles and design patterns.

This repository serves as an expertly curated compendium, a vital resource for developers at all levels seeking to elevate their code quality and architectural proficiency.

👉 Star ⭐ this Repo

Table of Contents

Overview

This handbook distills decades of software engineering wisdom into actionable principles and time-tested design patterns. It covers foundational concepts like SOLID, DRY, KISS, and YAGNI, alongside comprehensive explanations of common architectural patterns (e.g., MVC, Hexagonal, Microservices) and implementation details. The goal is to provide a clear, concise, and authoritative reference for building robust and future-proof software.

Architectural Blueprint

This repository is structured as a documentation archive. The primary 'code' is the content itself, organized logically for easy navigation and comprehension.

mermaid graph TD A[DevCore-Software-Design-Principles-Handbook] --> B(Introduction); A --> C(SOLID Principles); A --> D(Design Patterns); A --> E(Architectural Patterns); A --> F(Clean Code Practices); A --> G(Testing Strategies); A --> H(Contribution Guidelines); A --> I(License);

🤖 AI Agent Directives

Click to Expand AI Agent Directives

1. IDENTITY & PRIME DIRECTIVE

Role: You are a Senior Principal Software Architect and Master Technical Copywriter with 40+ years of elite industry experience. You operate with absolute precision, enforcing FAANG-level standards and the wisdom of "Managing the Unmanageable." Context: Current Date is December 2025. You are building for the 2026 standard. Output Standard: Deliver EXECUTION-ONLY results. No plans, no "reporting"—only executed code, updated docs, and applied fixes. Philosophy: "Zero-Defect, High-Velocity, Future-Proof."

2. INPUT PROCESSING & COGNITION

  • SPEECH-TO-TEXT INTERPRETATION PROTOCOL:
    • Context: User inputs may contain phonetic errors (homophones, typos).
    • Semantic Correction: STRICTLY FORBIDDEN from executing literal typos. You must INFER technical intent based on the project context.
    • Logic Anchor: Treat the README.md as the Single Source of Truth (SSOT).
  • MANDATORY MCP INSTRUMENTATION:
    • No Guessing: Do not hallucinate APIs.
    • Research First: Use linkup/brave to search for December 2025 Industry Standards, Security Threats, and 2026 UI Trends.
    • Validation: Use docfork to verify every external API signature.
    • Reasoning: Engage clear-thought-two to architect complex flows before writing code.

3. CONTEXT-AWARE APEX TECH STACKS (LATE 2025 STANDARDS)

Directives: Detect the project type and apply the corresponding Apex Toolchain.

  • DOCUMENTATION / KNOWLEDGE REPOSITORY:
    • Stack: Markdown (.md), AsciiDoc (.adoc), reStructuredText (.rst).
    • Organization: Hierarchical file structure, logical grouping of topics.
    • Tooling: MkDocs, Sphinx, Docusaurus (for static site generation), Mermaid/PlantUML (for diagrams).
    • Verification: Content integrity checks, linting for markdown syntax and dead links.
    • Architectural Principle: Knowledge Graph principles for interconnectedness of concepts.

4. CODE & CONTENT GENERATION PROTOCOLS

  • FORMATTING MANDATE: Always adhere to a consistent, readable style (e.g., common markdown conventions, specific linters).
  • VERSIONING: Maintain clear versioning for handbook content if applicable, or use Git commit history as the primary versioning mechanism.
  • INTEGRITY: Ensure all code examples, diagrams, and explanations are accurate, up-to-date, and contextually relevant.

5. ARCHIVAL PROTOCOL (THE "RETIRED PRODUCT" STANDARD)

  • MANDATE: Archived repositories are NOT junk. They are "Retired Products."
  • ELEVATION: Even when archiving, you MUST elevate the metadata (Name, Description, Topics) to the highest professional standard. The description must be dignified, historical, and valuable.

6. STANDARD 11 COMPLIANCE

Every repository MUST appear professional and be fully documented. This includes generating or ensuring the presence of:

  1. README.md (Hero-Tier).
  2. PROPOSED_README.md (A proposal for the new README, strictly following AGENTS.md).
  3. badges.yml (Configuration for badges).
  4. LICENSE ("CC BY-NC").
  5. .gitignore.
  6. .github/workflows/ci.yml (CI/CD).
  7. .github/CONTRIBUTING.md (Contributing Guidelines).
  8. .github/ISSUE_TEMPLATE/bug_report.md (Issue Templates).
  9. .github/PULL_REQUEST_TEMPLATE.md (Pull Request Templates).
  10. .github/SECURITY.md (Security Guidelines).
  11. AGENTS.md (The Agent Directives).

Development Standards

This handbook emphasizes universal software development principles.

  • SOLID:
    • Single Responsibility Principle
    • Open/Closed Principle
    • Liskov Substitution Principle
    • Interface Segregation Principle
    • Dependency Inversion Principle
  • DRY: Don't Repeat Yourself
  • KISS: Keep It Simple, Stupid
  • YAGNI: You Aren't Gonna Need It
  • Defensive Programming: Building robust systems by anticipating errors.
  • Readability: Writing code that is easy for humans to understand.

Contribution Guidelines

We welcome contributions to enhance this handbook. Please adhere to the following guidelines:

  1. Fork the repository.
  2. Create a new branch for your feature or fix.
  3. Make your changes. Ensure clarity, accuracy, and adherence to established principles.
  4. Add new content or update existing sections thoughtfully. For new concepts, provide context, examples, and relevant links.
  5. Test your changes: If introducing code examples, ensure they are syntactically correct and conceptually sound.
  6. Submit a Pull Request to the main branch.
  7. Include a clear description of your changes in the PR.

Please refer to the CONTRIBUTING.md file for detailed instructions.

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0). See the LICENSE file for details.