/clean-code-principles

{Rule Title}

{One or two sentence summary explaining the principle and why it matters. Should be clear and actionable.}

Bad Example

// Anti-pattern: {Brief description of what's wrong}

{Code example demonstrating the violation}

// Problems:
// 1. {Specific issue 1}
// 2. {Specific issue 2}
// 3. {Specific issue 3}

Why This Is Wrong:

• {Consequence 1}
• {Consequence 2}
• {Consequence 3}

Good Example

// Correct approach: {Brief description of the solution}

{Code example demonstrating proper implementation}

// Benefits:
// 1. {Benefit 1}
// 2. {Benefit 2}
// 3. {Benefit 3}

Alternative Approach (Optional):

// Another valid solution: {When this might be preferred}

{Alternative code example if applicable}

Why

Explanation of the principle and its benefits:

1. {Benefit Category 1}: {Detailed explanation}

2. {Benefit Category 2}: {Detailed explanation}

3. {Benefit Category 3}: {Detailed explanation}

4. {Benefit Category 4}: {Detailed explanation}

5. {Benefit Category 5}: {Detailed explanation}

6. {Benefit Category 6}: {Detailed explanation}

7. {Benefit Category 7}: {Detailed explanation}

When to Apply

• {Situation 1}
• {Situation 2}
• {Situation 3}
• {Situation 4}

When NOT to Apply (Optional)

// Acceptable exception: {Scenario where the rule can be relaxed}

{Code example of acceptable violation with clear reasoning}

// This is acceptable because:
// - {Reason 1}
// - {Reason 2}

Common Mistakes (Optional)

Mistake 1: {Common misunderstanding}

// ❌ Wrong
{Code showing mistake}

// ✅ Correct
{Code showing correction}

Mistake 2: {Another common issue}

// ❌ Wrong
{Code showing mistake}

// ✅ Correct
{Code showing correction}

Testing Implications (Optional)

How this principle affects testing:

// Test example showing improved testability
{Test code demonstrating benefits}

Real-World Example (Optional)

{Brief description of how this applies in production scenarios}

// Production scenario: {Description}
{Realistic code example}

Related Principles

• {Related Rule 1}: {Brief explanation of relationship}
• {Related Rule 2}: {Brief explanation of relationship}
• {Related Rule 3}: {Brief explanation of relationship}

Further Reading (Optional)

• {Resource title} - {URL or reference}
• {Resource title} - {URL or reference}

Language-Specific Notes (Optional)

TypeScript/JavaScript

{Language-specific considerations}

Python

{Language-specific considerations}

Java

{Language-specific considerations}

Go

{Language-specific considerations}

Template Guidelines

Frontmatter

• id: Use format {prefix}-{concept}-{specificity}. Must be unique and match filename.
• title: Full descriptive title, human-readable
• category: One of the 7 defined categories
• priority: critical (SOLID, Core) | high (Patterns, Org) | medium (Naming, Functions) | low (Comments)
• tags: 3-5 relevant tags for searchability
• related: 2-4 related rule IDs that commonly apply together

Content Structure

1. Title & Summary: Clear, one-sentence explanation
2. Bad Example: Show the anti-pattern with clear problems listed
3. Good Example: Show proper implementation with benefits
4. Why: 5-7 benefits explaining the value
5. When to Apply: Practical scenarios
6. Optional Sections: Add as needed for complex rules

Code Examples

• Use TypeScript for primary examples (language-agnostic)
• Keep examples focused and minimal
• Show realistic scenarios, not toy examples
• Include comments explaining key points
• Use ❌ for bad examples, ✅ for good examples

Writing Style

• Be direct and actionable
• Focus on "why" not just "what"
• Use active voice
• Keep explanations concise
• Provide context for decisions
• Assume intermediate developer knowledge

Length Guidelines

• Minimum: 200 lines (simple rules)
• Target: 300-400 lines (most rules)
• Maximum: 600 lines (complex patterns)

Quality Checklist

• Frontmatter complete and accurate
• Clear bad example with explained problems
• Clear good example with explained benefits
• At least 5 benefits in "Why" section
• Practical "When to Apply" scenarios
• Related rules referenced
• Code examples are realistic
• Comments explain key concepts
• Language-agnostic where possible
• Proofread for clarity and typos