code-readability
Skill0 starsChanged 9 months agoMITView on GitHub
Code readability patterns covering comments, function decomposition, nesting, naming conventions, and code structure. Use when evaluating whether code is easy to understand, deciding when and how to write comments, decomposing functions, reducing nesting depth, improving code structure, or reviewing code for readability. Covers comment strategy, function length, abstraction level mixing, nesting reduction, anonymous function readability, and making bad code visually obvious.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- LeahyCC/claude-skillstheir own version, first seen Nov 1, 2026
- PrairieAster-Ai/quality-butlertheir own version, first seen Jul 15, 2026
- nesco/skillstheir own version, first seen Apr 10, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- LeahyCC/claude-skills★ 3same name
- nesco/skills★ 0same name
- PrairieAster-Ai/quality-butler★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- code-antipatternsSkill
- code-namingSkill
- code-plan-auditSkill
- code-pruningSkill
- code-quality-foundationsSkill
- code-reviewSkill
- code-scope-boundariesSkill
- code-testing-qualitySkill
- code-yagniSkill
- error-handling-patternsSkill
- refactoring-patternsSkill
- software-tradeoffsSkill
The file
We split this skill into the rules it gives an agent
1 rule. 0 are common, 1 is distinctive, and 0 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 68
Before committing code, verify:
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Code Readability
Quick Reference
The Readability Checklist
| Dimension | Question | If No... |
| Names | Can I understand what this does from the names alone? | Rename variables, functions, classes |
| Comments | Do comments explain why, never what? | Delete "what" comments; improve names instead |
| Function length | Does each function do one thing at one abstraction level? | Extract methods |
| Nesting | Is nesting 2 levels or fewer? | Use early returns, extract helper functions |
| Consistency | Does this code follow the same style as surrounding code? | Adopt the project's conventions |
| Surprise factor | Would another engineer expect this behavior from reading the signature? | Rename or restructure to match expectations |
The Comment Decision Table
| Situation | Action | Example |
| Code does something non-obvious | Write a why comment | // Retry limit set to 3 per SLA with payments team |
| Name doesn't convey intent | Fix the name, don't add a comment | Rename d to elapsedDays |
| Complex algorithm or formula | Comment the approach, not the steps | // Uses Dijkstra's — graph is sparse |
| Workaround for a bug or limitation | Comment what and why | // Safari doesn't support ResizeObserver in iframes (WebKit #219765) |
| Legal or licensing requirement | Keep the comment | // SPDX-License-Identifier: MIT |
| Commented-out code | Delete it | Version control remembers |
| TODO or FIXME | Include a ticket reference | // TODO(CS-142): Replace with batch API |
| Section header in a long function | Extract a function instead | The function name becomes the "header" |
Documentation Value Hierarchy
| Level | Reach | Maintenance Cost | Reliability |
| Good names | Every call site | Zero (name is the code) | Always current |
| Type signatures | Every caller, IDE | Low (compiler verifies) | Enforced |
| Comments | Readers of this file only | Medium (can drift) | Trust but verify |
| External docs | Those who find them | High (often forgotten) | Frequently stale |
Decision Tables
"Should I write a comment?"
| The comment would explain... | Write it? | Instead... |
| What the code does | No | Improve the name or extract a function |
| Why the code does it this way | Yes | — |
| What a variable holds | No | Rename the variable |
| A workaround or hack | Yes | Include link to issue/ticket |
| The algorithm being used | Yes (if non-obvious) | — |
| A section of a long function | No | Extract the section into a named function |
"Is this function too long?"
| Signal | Verdict |
| Can describe in one sentence without "and" | Length is fine |
| Has blank-line-separated sections | Extract sections |
| Mixes abstraction levels | Split by level |
| Requires scrolling and mental bookmarking | Extract for readability |
| Every line contributes to one operation | Length is fine |
Readability Checklist
Before committing code, verify:
- Names reveal intent without needing comments
- Comments explain why, not what
- No commented-out code
- Functions operate at a single abstraction level
- Nesting is 2 levels or fewer
- Anonymous functions are short and their purpose is obvious
- Formatting follows project conventions
- Code follows the same patterns as surrounding code
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.