Skip to content

binayshaw7777/Leaflekt-Maps / .agents/skills/clean-code

clean-code

Verified

ALWAYS invoke this skill before writing, editing, generating, or refactoring ANY code. Do not write or modify code directly without first loading and following these Clean Code guidelines. Use when writing new functions/classes, refactoring existing code, reviewing code, fixing bugs, or any task that produces code output.

FileKindSize
SKILL.mdskill md4.2 KB
references/api_dto_clean.mdmarkdown3.0 KB
references/classes.mdmarkdown6.9 KB
references/comments.mdmarkdown5.7 KB
references/dataToDomainFlow.mdmarkdown7.4 KB
references/error-handling.mdmarkdown8.8 KB
references/formatting.mdmarkdown4.9 KB
references/functions.mdmarkdown12.9 KB
references/naming.mdmarkdown4.0 KB
references/rules-card.mdmarkdown3.6 KB
references/testing.mdmarkdown7.3 KB

references/naming.md

View on GitHub
# Naming Conventions

## Core Principle

Names should reveal intent. A reader should understand what a variable represents, what a function does, or what a class is responsible for without reading implementation details or comments.

## Variables

### Use Intention-Revealing Names

```python
# Bad
d = 7  # days

# Good
elapsed_days = 7
days_since_creation = 7
```

### Avoid Disinformation

Don't use names that vary in small ways:
```python
# Bad
user_list_for_processing
user_list_for_validation

# Good
users_to_process
users_to_validate
```

### Make Meaningful Distinctions

Avoid number series and noise words:
```python
# Bad
data1, data2, info, the_data

# Good
source_data, validated_data, user_profile
```

### Use Pronounceable Names

```python
# Bad
gen_ymdhms  # generation year, month, day, hour, minute, second

# Good
generation_timestamp
```

### Use Searchable Names

Single-letter names and numeric constants are hard to locate:
```python
# Bad
if s == 4:  # what is s? what is 4?

# Good
WORK_DAYS_PER_WEEK = 5
if task_count == WORK_DAYS_PER_WEEK:
```

### Avoid Encodings

Hungarian notation and member prefixes are obsolete:
```python
# Bad
str_name, m_description, i_count

# Good
name, description, count
```

## Class Names

Use nouns or noun phrases:
```python
# Good
Customer, WikiPage, Account, AddressParser

# Avoid
Manager, Processor, Data, Info (too generic)
```

## Function/Method Names

Use verbs or verb phrases:
```python
# Good
delete_page()
save_user()
is_valid()
get_name()
```

## Pick One Word Per Concept

Be consistent across your codebase:
```python
# Bad - pick ONE
fetch_user()
retrieve_account()
get_product()

# Good - consistent
get_user()
get_account()
get_product()
```

## Use Solution Domain Names

Programmers read your code, so use CS terms:
```python
# Good
job_queue  # queue is a well-known data structure
visitor_pattern  # pattern name from design patterns
```

## Use Problem Domain Names

When no programmer-centric name fits, use domain-specific terminology:
```python
# Good (for healthcare)
patient_chart
diagnosis_code
treatment_plan
```

## Add Meaningful Context

```python
# Bad - unclear context
first_name = "John"
last_name = "Doe"
street = "123 Main St"

# Good - clear context
class Address:
    def __init__(self):
        self.first_name = "John"
        self.last_name = "Doe"
        self.street = "123 Main St"
```

## Don't Add Gratuitous Context

```python
# Bad - redundant prefix
class GasStationDeluxe:
    def gas_station_deluxe_fill_up(self): pass

# Good
class GasStationDeluxe:
    def fill_up(self): pass
```

## Boolean Variables

Use predicates that read naturally:
```python
# Good
is_valid
has_permission
can_edit
should_retry
was_successful
```

## Collections

Use plural forms:
```python
# Good
users = []
active_customers = []
pending_orders = []
```

## Constants

Use UPPER_SNAKE_CASE:
```python
# Good
MAX_RETRY_COUNT = 3
DEFAULT_TIMEOUT_SECONDS = 30
API_BASE_URL = "https://api.example.com"
```

## Language-Specific Conventions

### Python
- `snake_case` for functions and variables
- `PascalCase` for classes
- `UPPER_SNAKE_CASE` for constants

### JavaScript/TypeScript
- `camelCase` for functions and variables
- `PascalCase` for classes
- `UPPER_SNAKE_CASE` for constants

### Java
- `camelCase` for methods and variables
- `PascalCase` for classes
- `UPPER_SNAKE_CASE` for constants

### Kotlin
- `camelCase` for functions and variables
- `PascalCase` for classes
- `UPPER_SNAKE_CASE` for constants

### C#
- `PascalCase` for public methods, properties, classes
- `camelCase` for local variables, parameters
- `_camelCase` for private fields (with underscore prefix)

## Anti-Patterns to Avoid

1. **Mental mapping** - `i`, `j`, `k` only acceptable in tiny loops
2. **Cute names** - `whack()` instead of `kill()`, `holyHandGrenade()` instead of `delete_items()`
3. **Puns** - Don't use same word for different purposes (`add` for math vs collection)
4. **Fear of long names** - Prefer clarity over brevity: `calculate_average_monthly_revenue()` over `calc_avg()`
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall