naming

Files (1)

• SKILL.md

SKILL.md (first lines)

# Naming Entities in Swift

The goal of a name is **clarity at the point of use**. A name succeeds when a reader who has never seen the call site can predict what it does, what type it is, and how it fits with the code around it. A name fails when it forces the reader to pause and think *"why is this one different?"* or *"what does that abbreviation stand for?"*

Apply these rules any time you introduce or rename a type, protocol, function, method, parameter, property, local variable, enum case, or generic parameter.

---

## 1. Hard rules

These are non-negotiable on this project.

### No abbreviations

Abbreviations force the reader to decode. Write the full word.

```swift
// No
let usr: User
let btnTitle: String
let createdDt: Date
let msgCount: Int
func calc(...) -> Int
class NoteMgr { ... }

// Yes
let user: User
let buttonTitle: String
let createdDate: Date
let messageCount: Int
func calculate(...) -> Int
class NotesManager { ... }
```

Narrow exceptions:
- **Deeply precedented domain terms** that everyone in that field would recognize: `sin`, `cos`, `url`, `id`, `json`, `html`. If a reasonable web search on the abbreviation alone would confirm the meaning, it is fine.
- **Established acronyms** already in the platform: `URL`, `UUID`, `HTTP`, `JSON`.

Acronyms follow the Swift case convention: uniformly upper-cased when capitalized (`URL`, `UTF8`), uniformly lower-cased otherwise (`urlString`, `jsonDecoder`). Never `Url` or `urlDecoderUrl`.

### No restating context

Inside a type, a property name should not repeat the enclosing type's name. The context is already obvious.

```swift
// No
struct BibleVersion {
    let versionTitle: String
    let bibleVersionAbbreviation: String
    let versionID: Int
}

// Yes
struct BibleVersion {
    let title: String
    let abbreviation: String
    let id: Int
}
```

Same for function parameters — do not restate the function's subject in each label:

```swift
// No
func updateVersion(versionTitle: String, versionAbbreviation: String) { ... }

// Yes
func updateVersion(title: String, abbreviation: String) { ... }
```

### Prefer product-focused names over technical names

When a shorter, more product-focused name conveys nearly all the meaning, use it. Multi-word internal-implementation names are a smell.

```swift
// No — technical, implementation-leaking, long
class NoteObjectStateSyncMachine { ... }
class UserDataRepositoryCoordinator { ... }
class PlanReadingProgressStateHandler { ... }

// Yes — what the thing is, in product terms
class NotesManager { ... }
class UserRepository { ... }
class PlanProgress { ... }
```

Ask *"what does this do for the product?"* and name from that vocabulary. Save specificity for the handful of cases where the role really is the distinguishing thing.

### A name must imply its type

A reader should be able to guess the type from the name without jumping to the declaration. Be consistent with the shape already used in nearby code.

| Type             | Suffix / shape                                  | Examples                                 |
| ---------------- | ----------------------------------------------- | ---------------------------------------- |
| `Date`           | `...Date`                                       | `createdDate`, `expirationDate`          |
| `TimeInterval`   | `...Duration`, `...Interval`, `...Seconds`      | `animationDuration`, `timeoutSeconds`    |
| `URL`            | `...URL`                                        | `avatarURL`, `shareURL`                  |
| `String` (URL)   | `...URLString`                                  | `avatarURLString`                        |
| `Bool`           | `is...`, `has...`, `can...`, `should...`        | `isHidden`, `hasUnread`, `canDismiss`    |
| Count            | `...Count`                                      | `messageCount`, `unreadCount`            |
| Array            | pluralize                                       | `friends`, `savedMoments`                |
| Dictionary       | `...By...` or descriptive pair                  | `usersByID`                              |
| Identifier       | `...ID` (when not the primary `id` of the type) | `userID`, `planID`                       |
| Closure          | verb phrase describing what it does             | `onTap`, `onLoad`, `didSelect`           |

Do not invent a new shape when a nearby one exists. If surrounding code uses `createdDate`, do not introduce `createdOn` or `createdAt` or `createdDt` — match the established pattern. **Never make the reader think "why is this similar-looking thing different from the other cases?"**

### Consistency with nearby code wins

Before naming a new thing, read the file and the module around it. If there is an existing convention — suffix, verb, parameter label order, collection naming — follow it. A technically better name that breaks a local pattern is worse than the local pattern.

---

## 2. Choosing the base name

### Name by role, not by type

Use the *role* the value plays in the code, not its class name.

From youversion/platform-sdk-swift, Apache-2.0.

More from youversion/platform-sdk-swift