{
    "slug": "coupling",
    "term": "Coupling",
    "category": "quality",
    "difficulty": "intermediate",
    "short": "The degree to which one module depends on another; high coupling makes changes expensive and testing difficult.",
    "long": "Coupling measures how much changing one module forces changes in others. Types range from loose (data coupling via parameters) to tight (content coupling where one module directly modifies another's internals). High coupling is a primary driver of brittle, hard-to-test code. It is reduced by programming to interfaces, using dependency injection, applying the Law of Demeter, and introducing well-defined boundaries between modules. Coupling and cohesion are twin concerns — high cohesion within a module naturally reduces coupling to other modules.",
    "aliases": [
        "tight coupling",
        "loose coupling",
        "module coupling"
    ],
    "tags": [
        "architecture",
        "oop",
        "principles",
        "solid"
    ],
    "misconception": "Any dependency between modules is bad coupling. Coupling is unavoidable — the goal is loose coupling, where modules depend on abstractions rather than concrete implementations, making them independently changeable and testable.",
    "why_it_matters": "Tightly coupled classes cannot be changed, tested, or reused independently — a change to one ripples through many, making the codebase increasingly expensive to modify.",
    "common_mistakes": [
        "Instantiating dependencies with new inside a class instead of injecting them.",
        "Accessing global state or singletons directly — hidden coupling that is invisible in the signature.",
        "Returning concrete types instead of interfaces — callers become coupled to the implementation.",
        "Reaching into chained objects: $order->getCustomer()->getAddress()->getCity() — violates Law of Demeter and couples deeply."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "cohesion",
        "dependency_injection",
        "law_of_demeter",
        "single_responsibility"
    ],
    "prerequisites": [
        "cohesion",
        "dependency_injection",
        "interfaces"
    ],
    "refs": [
        "https://en.wikipedia.org/wiki/Coupling_(computer_programming)"
    ],
    "bad_code": "// High coupling: PaymentService directly instantiates and calls Stripe SDK\nclass PaymentService {\n    public function charge(int $cents): void {\n        $stripe = new \\Stripe\\Charge();\n        $stripe->create(['amount' => $cents, 'currency' => 'usd']);\n    }\n}",
    "good_code": "// Low coupling: depends on an interface, not a concrete class\ninterface PaymentGateway {\n    public function charge(int $cents, string $currency): ChargeResult;\n}\n\nclass PaymentService {\n    public function __construct(private PaymentGateway $gateway) {}\n    public function charge(int $cents): ChargeResult {\n        return $this->gateway->charge($cents, 'usd');\n    }\n}\n\nclass StripeGateway implements PaymentGateway { ... }",
    "example_note": "Swap Stripe for Braintree by injecting a different implementation — PaymentService never changes.",
    "quick_fix": "Depend on abstractions (interfaces) not concretions; inject dependencies rather than instantiating them; measure coupling with fan-in/fan-out metrics",
    "severity": "medium",
    "effort": "high",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/coupling",
        "html_url": "https://codeclaritylab.com/glossary/coupling",
        "json_url": "https://codeclaritylab.com/glossary/coupling.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": "[Coupling](https://codeclaritylab.com/glossary/coupling) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/coupling"
            }
        }
    }
}