6.6 KiB

Raw Blame History

Create Code Example

task: id: create-code-example name: Create Code Example description: Develop working, tested, documented code example with explanation persona_default: code-curator inputs:

concept-to-demonstrate
programming-language
target-version steps:
Identify learning objective for this code example
Choose appropriate complexity level for target audience
Write working code with inline comments
Test code for correctness on target version
Write detailed explanation connecting code to concepts
Document prerequisites and dependencies
Add common mistakes section
Create variations and extensions section
Define testing approach
Use template code-example-tmpl.yaml with create-doc.md task
Run execute-checklist.md with code-quality-checklist.md
Run execute-checklist.md with code-testing-checklist.md
Run execute-checklist.md with version-compatibility-checklist.md output: docs/code-examples/{{example-name}}-example.md

Purpose

This task guides you through creating high-quality code examples that readers can trust, understand, and adapt. Every code example must work perfectly, follow best practices, and include comprehensive explanation.

Prerequisites

Before starting this task:

Clear understanding of the concept to demonstrate
Target programming language and version
Access to code-style-guides.md knowledge base
Ability to test code on target platform(s)

Workflow Steps

1. Identify Learning Objective

Define what this example teaches:

What specific concept or technique does this demonstrate?
Why is this approach useful?
When should readers apply this pattern?
How does this fit into the chapter's learning objectives?

Example: "Demonstrate JWT authentication middleware in Express.js to show secure API endpoint protection."

2. Choose Complexity Level

Select appropriate complexity:

Basic: Single concept, minimal dependencies, <30 lines
Intermediate: Multiple concepts, moderate structure, 30-100 lines
Advanced: Complex interactions, full patterns, 100+ lines

Match complexity to:

Reader's current skill level
Chapter position in book
Concept difficulty

3. Write Working Code

Create the code example:

Code Quality Requirements:

Code executes successfully without errors
Follows language-specific style guide (PEP 8, Airbnb JS, Google Java, etc.)
Uses descriptive variable and function names
Includes inline comments explaining WHY, not WHAT
Demonstrates proper error handling
Is DRY (Don't Repeat Yourself)
Avoids hardcoded values (use constants/config)
Includes all necessary imports/dependencies

Comment Guidelines:

Explain design decisions and tradeoffs
Highlight key concepts being demonstrated
Point out important details
Don't explain obvious syntax

4. Test Code Thoroughly

Verify the code works:

Run code on target version (e.g., Python 3.11+, Node 18+)
Test on target platforms (Windows/Mac/Linux if applicable)
Verify output matches expectations
Test edge cases and error conditions
Document exact test commands used
Include expected output

Testing Checklist:

Code runs without modification
Dependencies install correctly
Output is as documented
Error handling works
Edge cases covered

5. Write Detailed Explanation

Explain the code thoroughly:

Overall structure: How is the code organized?
Key concepts: What techniques are demonstrated?
Design decisions: Why this approach over alternatives?
Tradeoffs: What are the pros and cons?
Important details: What might readers miss?
Integration: How do parts work together?

Connect code to theory:

Reference chapter concepts
Explain how code implements theory
Show practical application of principles

6. Document Prerequisites and Setup

Provide complete setup instructions:

Prior knowledge required
Software/tools needed (with versions)
Dependencies to install (exact commands)
Environment setup (virtual env, Docker, etc.)
Configuration needed
Verification steps

Setup Template:

Prerequisites:
- Python 3.11 or higher
- pip package manager
- Virtual environment (recommended)

Setup:
1. Create virtual environment: python -m venv venv
2. Activate: source venv/bin/activate (Mac/Linux) or venv\Scripts\activate (Windows)
3. Install dependencies: pip install -r requirements.txt
4. Verify: python --version (should show 3.11+)

7. Add Common Mistakes Section

Document pitfalls:

What mistakes do beginners commonly make?
Why are these mistakes problematic?
How to identify these issues
Corrected examples

Example:

❌ Common Mistake: Hardcoding API keys

api_key = "sk-1234567890abcdef"


✅ Correct Approach: Use environment variables

api_key = os.getenv("API_KEY")

8. Create Variations and Extensions

Show how to adapt the example:

Alternative implementations
How to extend functionality
When to use variations
More advanced patterns building on this
Real-world applications

9. Generate Code Example Document

Use the create-doc.md task with code-example-tmpl.yaml template to create the structured code example document.

10. Validate Code Quality

Run checklists:

code-quality-checklist.md - Verify code follows standards
code-testing-checklist.md - Ensure thorough testing
version-compatibility-checklist.md - Confirm version support

Success Criteria

A completed code example should have:

Working code that executes successfully
Follows language-specific style guide
Inline comments explain WHY, not WHAT
Tested on target version(s)
Complete setup instructions
Detailed explanation connecting code to concepts
Prerequisites clearly documented
Common mistakes section
Variations and extensions
Testing approach defined
All checklists passed

Common Pitfalls to Avoid

Untested code: Always run code before documenting
Missing dependencies: List ALL requirements
Poor comments: Explain decisions, not syntax
Hardcoded values: Use constants or configuration
Insufficient error handling: Show proper error management
Outdated syntax: Use current language features
Platform assumptions: Test on target platforms
No explanation: Code alone doesn't teach

Next Steps

After creating the code example:

Add code file to chapter's code repository
Create unit tests (if appropriate)
Test on all supported platforms
Integrate into chapter narrative
Cross-reference from related sections

6.6 KiB Raw Blame History