skills.rest
software-mansion
software-mansionOFFICIAL
Explore all skills by this author →
Website𝕏@swmansionGitHub

expressive-code

Guides naming conventions and comment decisions for self-documenting source code.

835|90|Updated Jul 3, 2024
Search Tags:#naming conventions#self-documenting code#JSDoc#CLEAN CODE#doxygen#Code review#Code comments
One-click install
npx skills add https://github.com/software-mansion/react-native-audio-api --skill expressive-code
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: expressive-code
Source: https://github.com/software-mansion/react-native-audio-api/tree/main/.claude/skills/expressive-code
Command: npx skills add https://github.com/software-mansion/react-native-audio-api --skill expressive-code

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Developers often struggle to decide when code needs comments, how to name classes, functions, and variables clearly, and how to avoid comment anti-patterns that create maintenance burden. This Skill provides concrete principles for writing self-documenting code and applying comments only where syntax cannot express intent.

Core Features & Use Cases

  • Naming Principles: Rules for naming classes, functions, variables, and constants so names capture semantics fully, including guidance on handling complex entities and avoiding magic constants.
  • Comment Decision Framework: Criteria for when comments are necessary, such as documenting design decisions, complex algorithms, side effects, invariants, and behavioral contracts.
  • Anti-Pattern Detection: A catalog of common mistakes including commented-out code, changelog comments, redundant restatements, imprecise TODOs, and non-local references.
  • Use Case: When reviewing a pull request, use this Skill to evaluate whether a new function name is sufficiently expressive and whether the added comments follow Doxygen or JSDoc conventions without duplicating information.

Quick Start

Ask the AI to review the naming and comments in a source file using the expressive-code guidelines and suggest improvements.

Frequently Asked Questions about expressive-code

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write self-documenting code?▼

Self-documenting code uses names that capture semantics fully: class names describe traits, function names describe verbs, and variable names describe purpose. Prefer language syntax features over comments, and use named constants instead of magic values.

When should I add comments to code?▼

Add comments only when something cannot be expressed easily in code, such as reasons behind design decisions, steps in complex algorithms, non-obvious side effects, references to specifications, and behavioral contracts for interfaces or virtual methods.

What are common code comment anti-patterns?▼

Common anti-patterns include restating what code already says, leaving commented-out code, writing changelog or authorship notes, repeating the same comment in many places, referencing distant decisions, and writing vague TODOs without actionable next steps.

Which documentation style should I use for C++ vs TypeScript?▼

C and C++ typically use Doxygen, while JavaScript and TypeScript use JSDoc. Choose the documentation style that matches the language's idiomatic conventions so tooling and readers can parse it consistently.

How do I name a function or class with complex semantics?▼

First check whether the entity has too many responsibilities and can be divided. If division is infeasible, use a slightly longer name that captures the semantics, and add a comment explaining the complex behavior or contract that the name cannot express.

Related Skills

Explore More Software Engineering Skills→
uoyoCsharpuoyoCsharp
19

mvt-analyze-code

Analyze a codebase and generate a project context document with modules, entities, and business rules.

Community
Advanced
barikata1984barikata1984

quality-review

Automates git-based code quality reviews for commits and pull requests.

Community
Intermediate
alangebalangeb

code-review-workflow

Run pyscan, pyanalyze, ruff, and black to generate a unified markdown report.

Community
Intermediate
kmt-tkmt-t
1

C++ Linting

Validate C++ source code against defined naming and formatting rules.

Community
Advanced