{
    "slug": "speculative_generality",
    "term": "Speculative Generality",
    "category": "quality",
    "difficulty": "intermediate",
    "short": "Unused abstractions, parameters, or hooks added for hypothetical future use that complicate the codebase without present value.",
    "long": "Speculative generality is the code smell version of over-engineering: creating abstract classes with one subclass, adding unused parameters for flexibility, or writing hook points for requirements that don't exist yet. It violates YAGNI and adds cognitive overhead for every reader. Remove unused abstractions, parameters, and delegate methods that serve no current purpose — refactoring tools make re-introducing them straightforward if the need genuinely arises.",
    "aliases": [
        "over-engineering",
        "YAGNI violation",
        "future-proofing smell"
    ],
    "tags": [
        "code-smell",
        "yagni",
        "refactoring"
    ],
    "misconception": "Adding flexibility upfront saves refactoring time later. Speculative abstractions are rarely used as anticipated, add cognitive load now, and often need to be redesigned anyway when real requirements arrive — YAGNI exists because the cost of speculative code is immediate and certain.",
    "why_it_matters": "Code written for imagined future requirements adds complexity now for no current value — if the requirement never materialises, the abstraction is dead weight that obstructs simpler solutions.",
    "common_mistakes": [
        "Adding abstract base classes 'in case we need another implementation later' with only one concrete class.",
        "Plugin architectures for internal code that never needs to be pluggable.",
        "Configuration files for behaviour that has never varied and shows no sign of varying.",
        "Not applying YAGNI — the cost of adding abstraction when needed is almost always less than carrying premature abstraction."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "yagni",
        "lazy_class",
        "dead_code"
    ],
    "prerequisites": [
        "yagni",
        "kiss_principle",
        "premature_optimisation"
    ],
    "refs": [
        "https://refactoring.guru/smells/speculative-generality",
        "https://martinfowler.com/bliki/YAGNI.html",
        "https://wiki.c2.com/?SpeculativeGenerality"
    ],
    "bad_code": "// Built for flexibility nobody asked for yet\ninterface AbstractDataProviderFactoryInterface {\n    public function create(string \\$type): DataProviderInterface;\n}\nclass ConcreteDataProviderFactory implements AbstractDataProviderFactoryInterface {\n    public function create(string \\$type): DataProviderInterface {\n        return new DatabaseDataProvider(); // only one type ever exists\n    }\n}",
    "good_code": "// YAGNI — build what's needed today\nclass DatabaseDataProvider {\n    public function getData(): array { return \\$this->db->fetchAll(); }\n}\n// Add the interface/factory if and when a second provider materialises",
    "example_note": "Speculative abstractions add complexity now for benefits that may never arrive. Refactor when the second real case exists.",
    "quick_fix": "Delete the abstract base class with one concrete implementation, the plugin system with zero plugins, and the configuration option nobody uses — remove code for future requirements that may never come",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-15",
    "updated": "2026-04-28",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/speculative_generality",
        "html_url": "https://codeclaritylab.com/glossary/speculative_generality",
        "json_url": "https://codeclaritylab.com/glossary/speculative_generality.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Speculative Generality](https://codeclaritylab.com/glossary/speculative_generality) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/speculative_generality"
            }
        }
    }
}