software-design-philosophy

Malicious tool definition detected

Tool: SKILL.md [1/3] Description: --- name: software-design-philosophy description: 'Manage software complexity through deep modules, information hiding, and strategic programming.

Tool: SKILL.md [2/3] Description: the subtlest form - Decorators are frequent sources of leakage -- they expose the decorated interface - If two modules share knowledge, consider merging them or creating a new module that encapsulates the shared knowledge **Code applications:** | Context | Pattern | Example | |---------|---------|---------| | **Information hiding** | Encapsulate format details | One module owns the HTTP parsing logic; callers get structured objects | | **Temporal decomposition**

Tool: SKILL.md [3/3] Description: special event -- it is part of every feature's development **Code applications:** | Context | Pattern | Example | |---------|---------|---------| | **Tactical trap** | Resist quick-and-dirty fixes | Don't add a boolean parameter to handle "just this one special case" | | **Strategic investment** | Improve structure during feature work | When adding a feature, refactor the module interface if it has become awkward | | **Tactical tornado** | Recognize and interven

Malicious tool definition detected

Tool: references/comments-as-design.md [2/3] Description: # ValueError, and OSError in production). We log and continue rather # than crash the batch job. try: result = third_party_lib.process(data) except Exception as e: logger.warning(f"Processing failed for {data.id}: {e}") result = default_result() ``` **Bad implementation comments (just repeat the code):** ```python # Increment counter counter += 1 # Check if user is active if user.is_active: # Loop through items for item in items: # Return

Tool: references/comments-as-design.md [3/3] Description: comments in a separate documentation file.

Malicious tool definition detected

Tool: references/complexity-symptoms.md [1/2] Description: # Complexity: Symptoms, Causes, and Measurement The single greatest challenge in software engineering is managing complexity.

Tool: references/complexity-symptoms.md [2/2] Description: on global state set by module B | **Goal:** You cannot eliminate dependencies entirely (software is interconnected), but you can: 1.

Malicious tool definition detected

Tool: references/deep-modules.md [1/2] Description: # Deep vs Shallow Modules The concept of module depth is one of the most powerful ideas in Ousterhout's philosophy.

Tool: references/deep-modules.md [2/2] Description: Fewer, deeper classes almost always produce simpler systems than many shallow ones.

Malicious tool definition detected

Tool: references/general-vs-special.md [1/2] Description: # General-Purpose vs Special-Purpose Modules One of the most important design decisions is how general-purpose or special-purpose a module's interface should be. Ousterhout advocates for a "somewhat general-purpose" approach: general enough to avoid special cases, specific enough to avoid over-engineering. ## The Spectrum ``` Too Special ←————————————————————————→ Too General (bloated (sweet spot: (wasted effort, with "somewhat unnecessar

Tool: references/general-vs-special.md [2/2] Description: usually negligible) | ### When Configuration Is Justified Configuration parameters are justified when: 1. **Different callers genuinely need different values** (not just "might someday need") 2.

Malicious tool definition detected

Tool: references/information-hiding.md [1/2] Description: # Information Hiding and Information Leakage Information hiding is the most important technique for achieving deep modules. It was first articulated by David Parnas in 1971 and remains the foundation of good software design. Information leakage is its opposite -- and one of the most common sources of unnecessary complexity.

Tool: references/information-hiding.md [2/2] Description: now()}} # In webhook_handler.py: def format_error(code, message): return {"error": {"code": code, "message": message, "timestamp": now()}} ``` **After:** ```python # In error_format.py: def format_error(code, message): return {"error": {"code": code, "message": message, "timestamp": now()}} # Both api_handler and webhook_handler import from error_format ``` ### Strategy 3: Push Knowledge Downward Move knowledge from callers into the modul

Malicious tool definition detected

Tool: references/strategic-programming.md [1/3] Description: # Strategic vs Tactical Programming The distinction between strategic and tactical programming is not about specific techniques -- it is about mindset.

Tool: references/strategic-programming.md [2/3] Description: it" is a common principle, but Ousterhout gives it teeth: every change should include at least one design improvement. Not every change needs a major refactoring, but every change should make some small improvement to the system's design.

Tool: references/strategic-programming.md [3/3] Description: simpler or more complex?