playbooks

home / skills / baz-scm / awesome-reviewers / code-readability

code-readability skill

/_skills/code-readability

This skill helps you write clean, self-documenting code by prioritizing clarity, meaningful names, and straightforward structure for maintainability.

npx playbooks add skill baz-scm/awesome-reviewers --skill code-readability

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.6 KB
---
name: code-readability
description: Writing clean, understandable, and self-documenting code that is easy to review and maintain over time.
version: '1.0'
---
# Code Readability & Maintainability

Writing **clean code** is a superpower for long-term productivity. Developers should prioritize clarity and explicitness over clever brevity. Code that clearly communicates its intent is easier for teammates (and future you) to understand and modify. High readability also reduces the chance of bugs – clear, well-structured code is more maintainable and less prone to surprise behaviors.

## Examples
- Using meaningful variable and function names (`isServerConnected` instead of `enabled`) to convey intent.
- Replacing a cryptic one-liner with a few well-named intermediate variables that make the logic obvious.

## Guidelines
- **Descriptive Naming:** Choose specific, descriptive names for variables, functions, and classes. Names should communicate intent and avoid ambiguity. For example, prefer `getUserProfile()` over `getData()` to make the code self-explanatory.
- **Clarity Over Cleverness:** Opt for explicit and straightforward code constructs rather than implicit or overly clever ones. For instance, use clear type conversions and named constants instead of magic numbers or implicit casts. This improves readability and avoids confusion.
- **Maintainability:** Keep code structure simple and organized. Write code in a way that reduces cognitive load on the reader – e.g. clear logic flow and consistent style. Clean, readable code is easier to debug and prevents subtle bugs that can arise from unclear operations.

Overview

This skill helps authors write clean, understandable, and self-documenting code that is easy to review and maintain over time. It focuses on naming, clarity, and structure so code communicates its intent without heavy external documentation. The result is fewer bugs, faster reviews, and smoother handoffs between teammates.

How this skill works

The skill inspects code for readability patterns: naming quality, explicitness of logic, use of magic numbers, and clarity of flow. It suggests concrete rewrites such as more descriptive names, intermediate variables to expose intent, and replacement of implicit conversions with explicit, named constructs. It also highlights areas where simplification improves maintainability.

When to use it

  • During pull request reviews to highlight readability regressions
  • When refactoring legacy code to make intent explicit
  • Before handing work off to another team or new engineer
  • When writing library or API code that others will depend on
  • While applying consistent style and naming conventions across a codebase

Best practices

  • Prefer descriptive names that convey intent (e.g., getUserProfile over getData)
  • Choose clarity over clever one-liners; favor explicit constructs
  • Replace magic numbers and implicit casts with named constants and conversions
  • Introduce well-named intermediate variables to expose complex logic
  • Keep functions short and focused; single responsibility improves readability

Example use cases

  • Suggest renaming ambiguous variables and functions in a code review
  • Refactor a dense expression into several named steps for easier debugging
  • Audit a module for hidden side effects or implicit type coercion
  • Convert magic literals into constants with descriptive names
  • Evaluate API surface for self-documenting method and parameter names

FAQ

How strict should naming be?

Aim for names that make intent obvious while staying concise; prefer clarity over micro-optimization of length.

When is a one-liner acceptable?

Use one-liners only when they remain immediately clear to a reader; otherwise split into named steps.