code-generation

name	code-generation
description	Standards and best practices for generating educational code examples. Ensures consistency, readability, and pedagogical value in all code snippets.
version	1.0.0
tags	["coding","standards","education","python","best-practices"]

Code Generation Skill

This skill defines the standards for generating code examples in educational content. The goal is to produce code that is not just functional, but exemplary—teaching best practices by example.

Core Philosophy

1. Readability First: Code is read more often than written. Optimize for the reader.
2. Pedagogical Clarity: Avoid "clever" one-liners. Prefer explicit, step-by-step logic.
3. Standard Compliance: Strictly follow language-specific style guides (e.g., PEP 8 for Python).
4. Self-Documenting: Variable names should explain their purpose. Comments should explain why, not what.

General Standards

1. Naming Conventions

• Descriptive Names: Use user_age instead of a, total_price instead of tp.
• No Single Letters: Exception for loop counters (i, j) in generic contexts, but prefer for item in items.
• Consistency: Stick to the language's standard (snake_case for Python, camelCase for JS).

2. Comments and Documentation

• Explain the 'Why':
  • ❌ x = x + 1 # Increment x
  • ✅ retry_count += 1 # Track attempts to prevent infinite loop
• Docstrings: All functions and classes must have a docstring explaining inputs, outputs, and purpose.
• Inline Comments: Use sparingly for complex logic.

3. Error Handling

• No Silent Failures: Never use bare try...except (Python) or empty catch blocks.
• Explicit Exceptions: Catch specific errors (e.g., ValueError, FileNotFoundError).
• Educational Value: Show students how to handle errors gracefully.

4. "No Magic Numbers"

• Define constants for literal values.
• ❌ if status == 4:
• ✅ READY_STATUS = 4; if status == READY_STATUS:

Language-Specific Rules

Python

• Style: Strict PEP 8.
• Type Hints: Use type hints for function arguments and return values.

  def calculate_total(price: float, tax_rate: float) -> float:
      """Calculates total price including tax."""
      return price * (1 + tax_rate)
  

• f-strings: Prefer f-strings over % formatting or .format().

JavaScript / TypeScript

• Style: Standard JS style (Airbnb or similar).
• Variables: Use const by default, let only when reassignment is needed. Never var.
• Async/Await: Prefer async/await over raw Promises.

Pedagogical Patterns

1. The "Before and After"

When teaching a better way to do something, show the "naive" approach first (labeled as such), then the "professional" approach.

2. Progressive Complexity

Start with a minimal working example. Add complexity (error handling, edge cases) in subsequent steps.

3. Runnable Snippets

Ensure code snippets are self-contained and runnable whenever possible. Include necessary imports.

Quality Checklist

Before finalizing any code snippet, verify:

• Does it follow the language style guide?
• Are variable names descriptive?
• Are "magic numbers" replaced with constants?
• Is there a docstring/comment explaining the purpose?
• Is error handling appropriate for the context?
• If it's a "bad example", is it clearly labeled?