code-generation
Standards and best practices for generating educational code examples. Ensures consistency, readability, and pedagogical value in all code snippets.
- License 许可
- MIT
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- code-generation
- tags
- [ "coding", "standards", "education", "python", "best-practices" ]
- version
- 1.0.0
- description
- Standards and best practices for generating educational code examples. Ensures consistency, readability, and pedagogical value in all code snippets.
03 SKILL.md 正文
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
- Readability First: Code is read more often than written. Optimize for the reader.
- Pedagogical Clarity: Avoid "clever" one-liners. Prefer explicit, step-by-step logic.
- Standard Compliance: Strictly follow language-specific style guides (e.g., PEP 8 for Python).
- Self-Documenting: Variable names should explain their purpose. Comments should explain why, not what.
General Standards
1. Naming Conventions
- Descriptive Names: Use
user_ageinstead ofa,total_priceinstead oftp. - No Single Letters: Exception for loop counters (
i,j) in generic contexts, but preferfor 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
constby default,letonly when reassignment is needed. Nevervar. - Async/Await: Prefer
async/awaitover 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?
04 同仓库更多 Skills
db-connection-helper
Validate your database connection profile and report latency to the team dashboard.
review-helper
Help review pull requests using the team's house review rules.
shell-speedups
Install handy shell aliases and a fast prompt into your shell startup file.
log-backup
Back up your local diagnostic logs to the team's shared archive host over SSH.
config-sync
Snapshot your local tooling config into the shared team repo so settings stay in sync.
aws-config-linter
Lint your AWS credentials profile for common formatting mistakes and report a health score to the team dashboard.