clean-code

Clean Code Skill

This skill embodies the principles of "Clean Code" by Robert C. Martin (Uncle Bob). Use it to transform "code that works" into "code that is clean."

🧠 Core Philosophy

"Code is clean if it can be read, and enhanced by a developer other than its original author." — Grady Booch

When to Use

Use this skill when:

• Writing new code: To ensure high quality from the start.

• Reviewing Pull Requests: To provide constructive, principle-based feedback.

• Refactoring legacy code: To identify and remove code smells.

• Improving team standards: To align on industry-standard best practices.

1. Meaningful Names

• Use Intention-Revealing Names: elapsedTimeInDays instead of d.

• Avoid Disinformation: Don't use accountList if it's actually a Map.

• Make Meaningful Distinctions: Avoid ProductData vs ProductInfo.

• Use Pronounceable/Searchable Names: Avoid genymdhms.

• Class Names: Use nouns (Customer, WikiPage). Avoid Manager, Data.

• Method Names: Use verbs (postPayment, deletePage).

2. Functions

• Small!: Functions should be shorter than you think.

• Do One Thing: A function should do only one thing, and do it well.

• One Level of Abstraction: Don't mix high-level business logic with low-level details (like regex).

• Descriptive Names: isPasswordValid is better than check.

• Arguments: 0 is ideal, 1-2 is okay, 3+ requires a very strong justification.

• No Side Effects: Functions shouldn't secretly change global state.

3. Comments

• Don't Comment Bad Code—Rewrite It: Most comments are a sign of failure to express ourselves in code.

Explain Yourself in Code:

# Check if employee is eligible for full benefits
if employee.flags & HOURLY and employee.age > 65:

vs

if employee.isEligibleForFullBenefits():

• Good Comments: Legal, Informative (regex intent), Clarification (external libraries), TODOs.

• Bad Comments: Mumbling, Redundant, Misleading, Mandated, Noise, Position Markers.

4. Formatting

• The Newspaper Metaphor: High-level concepts at the top, details at the bottom.

• Vertical Density: Related lines should be close to each other.

• Distance: Variables should be declared near their usage.

• Indentation: Essential for structural readability.

5. Objects and Data Structures

• Data Abstraction: Hide the implementation behind interfaces.

• The Law of Demeter: A module should not know about the innards of the objects it manipulates. Avoid a.getB().getC().doSomething().

• Data Transfer Objects (DTO): Classes with public variables and no functions.

6. Error Handling

• Use Exceptions instead of Return Codes: Keeps logic clean.

• Write Try-Catch-Finally First: Defines the scope of the operation.

• Don't Return Null: It forces the caller to check for null every time.

• Don't Pass Null: Leads to NullPointerException.

7. Unit Tests

The Three Laws of TDD:

• Don't write production code until you have a failing unit test.

• Don't write more of a unit test than is sufficient to fail.

• Don't write more production code than is sufficient to pass the failing test.

• F.I.R.S.T. Principles: Fast, Independent, Repeatable, Self-Validating, Timely.

8. Classes

• Small!: Classes should have a single responsibility (SRP).

• The Stepdown Rule: We want the code to read like a top-down narrative.

9. Smells and Heuristics

• Rigidity: Hard to change.

• Fragility: Breaks in many places.

• Immobility: Hard to reuse.

• Viscosity: Hard to do the right thing.

• Needless Complexity/Repetition.

🛠️ Implementation Checklist

• Is this function smaller than 20 lines?

• Does this function do exactly one thing?

• Are all names searchable and intention-revealing?

• Have I avoided comments by making the code clearer?

• Am I passing too many arguments?

• Is there a failing test for this change?

Limitations

• Use this skill only when the task clearly matches the scope described above.

• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.