Java Clean Names

---
name: java-clean-names
description: Enforces naming in Java 21+ — descriptive names, names matched to scope, no Hungarian notation or I-prefixed interfaces, no meaningless suffixes like Manager or Helper, and names that reveal side effects. Use when naming or renaming variables, fields, methods, classes, records, interfaces, or packages in Java, and when the user asks "rename this", "better name", "what should I call this", or the code shows cryptic identifiers, `Impl` suffixes, or getters that mutate.
---

# Clean names in Java

## Reveal intent

If a name needs a comment to explain it, the name is wrong.

```java
// Bad
int d;
List<int[]> theList;

// Good
int elapsedDays;
List<Cell> flaggedCells;
```

```java
// Bad — what does this return?
public List<User> get(int x) { ... }

// Good
public List<User> findUsersOlderThan(int minimumAge) { ... }
```

## Name at the right level of abstraction

The name describes what the caller gets, not how it is stored.

```java
// Bad — leaks the implementation
Map<String, List<Order>> getOrderHashMapByCustomerId()

// Good
Map<String, List<Order>> ordersByCustomer()
```

Changing a `HashMap` to a `TreeMap` should not require renaming anything.

## Length matches scope

Short names are fine in short scopes and wrong at class or package level.

```java
// Good — lifetime is one line
orders.forEach(o -> total = total.add(o.amount()));

// Good — visible everywhere, so it earns its length
private static final Duration DEFAULT_CONNECTION_TIMEOUT = Duration.ofSeconds(30);

// Bad — a field nobody can interpret
private int max;
```

`var` shifts weight onto the name — with the type gone from the left, the right side must carry it.

```java
var result = process(input);              // bad — two mysteries
var settledInvoices = process(input);     // good
```

## No encodings

Modern tooling makes type prefixes noise.

```java
// Bad
String strName;
List<User> lstUsers;
private int m_count;
interface IUserRepository {}
class UserRepositoryImpl implements IUserRepository {}

// Good
String name;
List<User> users;
private int count;
interface UserRepository {}
class JdbcUserRepository implements UserRepository {}
```

`Impl` says nothing. Name the implementation after what makes it different: `JdbcUserRepository`, `InMemoryUserRepository`, `CachingUserRepository`.

## Avoid noise words

`Manager`, `Processor`, `Helper`, `Util`, `Data`, `Info`, `Service` attached to everything stop distinguishing anything. `UserData`, `UserInfo` and `User` cannot be told apart by a reader deciding which to use.

If a class is genuinely a bag of static methods, the name should say what they operate on (`Durations`, `Collectors`) — a plural noun, not `DurationUtils`.

## Names describe side effects

```java
// Bad — a getter that mutates
public Config getConfig() {
    if (config == null) {
        config = loadFromDisk();   // hidden write
    }
    return config;
}

// Good
public Config getOrLoadConfig() { ... }
```

A method named `validate` that also saves is a bug waiting for a reader. Either rename it or split it.

## Follow the conventions

Classes and records are `PascalCase` nouns. Methods are `camelCase` verbs. Constants are `UPPER_SNAKE_CASE`. Packages are lowercase, singular, no underscores. Booleans read as predicates: `isActive`, `hasExpired`, `canRetry`.

Records make the accessor convention explicit — a record component `amount()` has no `get` prefix. Follow that in new domain types generally: `order.total()` reads better than `order.getTotal()`, and `get` earns its place only where a framework requires it.

## Use one word per concept

Pick `find`, `fetch`, or `retrieve` and use it everywhere for the same operation. Three synonyms across three classes force the reader to check whether the difference is meaningful.

Conventional pairs, used consistently: `create`/`delete`, `add`/`remove`, `start`/`stop`, `open`/`close`, `first`/`last`.