AgentSkillsCN

self-documenting-code-checklists

当您编写、审查或重构代码时，可使用此技能，确保代码具备自我文档化的能力。将这些检查清单应用于函数、数据命名、数据组织，以及整体代码布局，从而在无需依赖注释的前提下，提升代码的清晰度与可维护性。

SKILL.md
--- frontmatter
name: self-documenting-code-checklists
description: Use this skill when writing, reviewing, or refactoring code to ensure it is self-documenting. Apply these checklists to routines, data naming, data organization, and overall code layout to improve code clarity and maintainability without relying on comments.

Self-Documenting Code Checklists

Self-documenting code communicates its purpose through clear naming, structure, and organization rather than through comments. Use these checklists to evaluate and improve code clarity.

When to Use

  • •Writing new routines, functions, or methods
  • •Conducting code reviews
  • •Refactoring existing code for maintainability
  • •Evaluating code quality and readability

Routine Design Checklist

Apply this checklist when designing or reviewing functions, methods, and subroutines:

  • • Naming accuracy: Does the routine name accurately describe what it does?
  • • Single responsibility: Does the routine perform one well-defined task?
  • • Modularity: Have all parts that could benefit from being independent been extracted into their own routines?
  • • Interface clarity: Is the routine's interface obvious and clear?

Action: If any item is "no," refactor the routine.

Data Naming Checklist

Apply this checklist when declaring or naming variables, constants, and types:

  • • Type descriptiveness: Is the type name descriptive enough to help document data declarations?
  • • Variable naming: Are variables named well?
  • • Purpose consistency: Is each variable used only for the purpose its name indicates?
  • • Loop counters: Do loop counters use more informative names than i, j, k?
  • • Enumerated types: Are well-named enums used instead of ad-hoc flags or booleans?
  • • Named constants: Are named constants used instead of magic numbers or magic strings?
  • • Naming conventions: Do naming conventions distinguish between type names, enums, named constants, local variables, class variables, and global variables?

Action: Rename variables or introduce constants if magic numbers or ambiguous names are found.

Data Organization Checklist

Apply this checklist when organizing data access and structures:

  • • Helper variables: Are additional variables used where needed to improve clarity?
  • • Reference locality: Are references to variables grouped together?
  • • Type simplicity: Are data types simple to minimize complexity?
  • • Abstract access: Is complex data accessed through abstract access routines (abstract data types)?

Action: Refactor data structures or introduce intermediate variables to simplify logic.

Layout and Design Checklist

Apply this checklist when reviewing code layout or high-level design:

  • • Logical layout: Does the program's layout display its logical structure?
  • • Directness: Is the code straightforward, avoiding "clever" tricks?
  • • Hidden details: Are implementation details hidden as much as possible?
  • • Domain terminology: Is the program written using problem-domain terminology rather than computer science or programming language terminology?

Action: Format and simplify code if it is too "clever" or the layout is confusing.