{
    "slug": "side_effects",
    "term": "Side Effects",
    "category": "quality",
    "difficulty": "intermediate",
    "short": "Observable changes a function makes beyond returning a value — modifying global state, I/O, mutation of arguments — that make code harder to reason about.",
    "long": "Side effects include: modifying global or class-level state, writing to files or databases, sending emails, mutating arguments passed by reference, and throwing exceptions. They are necessary for useful programs but should be isolated to well-defined boundaries and minimised in business logic. Unexpected side effects are a major source of bugs. The command-query separation principle (CQS) formalises this: methods that return values should not modify state, and methods that modify state should not return values.",
    "aliases": [
        "function side effects",
        "hidden side effects",
        "implicit state change"
    ],
    "tags": [
        "functional",
        "quality",
        "testing",
        "principles"
    ],
    "misconception": "Side effects are always bad and should be eliminated. Side effects — writing to a database, sending an email — are the point of most applications. The goal is to isolate and make them explicit, not eliminate them.",
    "why_it_matters": "Hidden side effects make functions unpredictable — a caller cannot reason about the full impact of calling a function without reading its implementation, causing bugs when functions are composed or reordered.",
    "common_mistakes": [
        "Functions that modify global state, static properties, or their arguments without signalling it in the signature.",
        "Constructors with side effects — database writes, HTTP calls, or file I/O in __construct().",
        "Not distinguishing between acceptable necessary side effects (persisting data) and hidden accidental ones.",
        "Functions that return different values for the same input due to hidden state — breaks caching and testing."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "pure_function",
        "command_query_separation",
        "immutability"
    ],
    "prerequisites": [
        "pure_function",
        "single_responsibility",
        "command_query_separation"
    ],
    "refs": [
        "https://en.wikipedia.org/wiki/Side_effect_(computer_science)"
    ],
    "bad_code": "// Hidden side effects — callers can't predict what changes\nfunction calculateTotal(array \\$cart): float {\n    \\$this->lastCalculated = time();          // hidden mutation\n    \\$this->analytics->track('cart_viewed');  // hidden I/O\n    \\$total = array_sum(array_column(\\$cart, 'price'));\n    \\$this->cache->set('cart_total', \\$total); // hidden write\n    return \\$total;\n}",
    "good_code": "// Pure calculation — no side effects\nfunction calculateTotal(array \\$cart): float {\n    return array_sum(array_column(\\$cart, 'price'));\n}\n\n// Side effects handled explicitly by the caller\n\\$total = calculateTotal(\\$cart);\n\\$this->analytics->track('cart_viewed');\n\\$this->cache->set('cart_total:' . \\$cartId, \\$total);",
    "quick_fix": "Separate commands (write, no return) from queries (read, return value) — functions that do both are harder to test and reason about",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/side_effects",
        "html_url": "https://codeclaritylab.com/glossary/side_effects",
        "json_url": "https://codeclaritylab.com/glossary/side_effects.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": "[Side Effects](https://codeclaritylab.com/glossary/side_effects) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/side_effects"
            }
        }
    }
}