code-generation

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.

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:

Python

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

```python

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.

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.

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?