USB-Meter
/
Documentation
/
Project Structure and Naming.md
Newer
■
■
■
■
■
■
■
■
■
■
Older
139 lines
|
5.113kb
| 1 |
# Project Structure and Naming |
|
| 2 | ||
| 3 |
This document defines how we name SwiftUI views and how we place files in the project so the codebase matches the product language and the UI hierarchy. |
|
| 4 | ||
| 5 |
## Core Rules |
|
| 6 | ||
| 7 |
- Name folders after the feature or navigation surface the user sees. |
|
| 8 |
- Example: the Home tab lives in `Views/Meter/Tabs/Home/`, not in `Connection/`. |
|
| 9 |
- Name the main view in a folder after the feature it owns. |
|
| 10 |
- Example: `MeterHomeTabView.swift` is the root view for the meter Home tab. |
|
| 11 |
- Keep the file name and the Swift type name identical. |
|
| 12 |
- Example: `MeterOverviewSectionView.swift` contains `MeterOverviewSectionView`. |
|
| 13 |
- Prefer product language over implementation history. |
|
| 14 |
- If the app says "Home", use `Home` in code instead of older terms like `Connection`. |
|
| 15 |
- Use `Components/` only for reusable building blocks. |
|
| 16 |
- A component is used in multiple views or is clearly meant to be reused. |
|
| 17 |
- Example: `MeterInfoCardView` and `MeterInfoRowView`. |
|
| 18 |
- Use `Subviews/` for views that belong to a single parent feature. |
|
| 19 |
- A subview is used once or is tightly coupled to one screen/tab. |
|
| 20 |
- Example: `Views/Meter/Tabs/Home/Subviews/MeterOverviewSectionView.swift`. |
|
| 21 |
- Use `Sheets/` for modal flows presented from another screen. |
|
| 22 |
- Example: `Views/Meter/Sheets/AppHistory/AppHistorySheetView.swift`. |
|
| 23 |
- Keep reusable components close to the narrowest shared owner. |
|
| 24 |
- If a component is reused only inside Meter screens, keep it in `Views/Meter/Components/`. |
|
| 25 |
- Do not move it to app-wide `Views/Components/` unless it is truly generic. |
|
| 26 |
- Keep small support types next to their owner. |
|
| 27 |
- If a helper type exists for one view only, keep it in the same file or the same feature subfolder. |
|
| 28 |
- Avoid vague verbs or placeholder names. |
|
| 29 |
- Prefer `MeterNameEditorView` over `EditNameView`. |
|
| 30 |
- Prefer `MeterConnectionActionView` over `ConnectionPrimaryActionView`. |
|
| 31 |
- A folder should describe ownership, not implementation detail. |
|
| 32 |
- `Home/Subviews/` is better than `Connection/Components/` when the views are single-use parts of the Home tab. |
|
| 33 | ||
| 34 |
## Naming Checklist |
|
| 35 | ||
| 36 |
Before adding or renaming a file, check: |
|
| 37 | ||
| 38 |
- Can someone guess the file location from the screen name? |
|
| 39 |
- Does the type name say what the view renders? |
|
| 40 |
- Is this reused enough to deserve `Components/`? |
|
| 41 |
- If it is single-use, does it live under the parent feature's `Subviews/` folder? |
|
| 42 |
- Does the code use the same words as the UI? |
|
| 43 | ||
| 44 |
## Current Meter Tab Pattern |
|
| 45 | ||
| 46 |
Use this structure for Meter tab work: |
|
| 47 | ||
| 48 |
```text |
|
| 49 |
Views/Meter/ |
|
| 50 |
Components/ |
|
| 51 |
MeasurementChartView.swift |
|
| 52 |
MeterInfoCardView.swift |
|
| 53 |
MeterInfoRowView.swift |
|
| 54 |
Sheets/ |
|
| 55 |
AppHistory/ |
|
| 56 |
AppHistorySheetView.swift |
|
| 57 |
Subviews/ |
|
| 58 |
AppHistorySampleView.swift |
|
| 59 |
ChargeRecord/ |
|
| 60 |
ChargeRecordSheetView.swift |
|
| 61 |
Subviews/ |
|
| 62 |
ChargeRecordMetricsTableView.swift |
|
| 63 |
DataGroups/ |
|
| 64 |
DataGroupsSheetView.swift |
|
| 65 |
Subviews/ |
|
| 66 |
DataGroupRowView.swift |
|
| 67 |
Tabs/ |
|
| 68 |
Home/ |
|
| 69 |
MeterHomeTabView.swift |
|
| 70 |
Subviews/ |
|
| 71 |
MeterConnectionActionView.swift |
|
| 72 |
MeterConnectionStatusBadgeView.swift |
|
| 73 |
MeterOverviewSectionView.swift |
|
| 74 |
Live/ |
|
| 75 |
MeterLiveTabView.swift |
|
| 76 |
Subviews/ |
|
| 77 |
LoadResistanceIconView.swift |
|
| 78 |
MeterLiveContentView.swift |
|
| 79 |
MeterLiveMetricRange.swift |
|
| 80 |
Chart/ |
|
| 81 |
MeterChartTabView.swift |
|
| 82 |
Settings/ |
|
| 83 |
MeterSettingsTabView.swift |
|
| 84 |
Subviews/ |
|
| 85 |
MeterCurrentScreenSummaryView.swift |
|
| 86 |
MeterNameEditorView.swift |
|
| 87 |
MeterScreenControlButtonView.swift |
|
| 88 |
MeterScreenControlsView.swift |
|
| 89 |
ScreenBrightnessEditorView.swift |
|
| 90 |
ScreenTimeoutEditorView.swift |
|
| 91 |
``` |
|
| 92 | ||
| 93 |
## Current Charged Device Pattern |
|
| 94 | ||
| 95 |
Use the same root categories as Meter work: shared components first, screen/detail roots next, then sheets and sidebar-specific views. |
|
| 96 | ||
| 97 |
```text |
|
| 98 |
Views/ChargedDevices/ |
|
| 99 |
Components/ |
|
| 100 |
ChargedDeviceDetailTabBarView.swift |
|
| 101 |
ChargedDeviceEditorScaffoldView.swift |
|
| 102 |
ChargedDeviceIdentityViews.swift |
|
| 103 |
ChargedDeviceLibraryRowView.swift |
|
| 104 |
ChargedDeviceQRCodeView.swift |
|
| 105 |
ChargedDeviceSidebarCardView.swift |
|
| 106 |
Details/ |
|
| 107 |
ChargedDeviceDetailView.swift |
|
| 108 |
Sessions/ |
|
| 109 |
ChargedDeviceActiveSessionView.swift |
|
| 110 |
ChargedDeviceSessionDetailView.swift |
|
| 111 |
ChargedDeviceSessionsView.swift |
|
| 112 |
Sheets/ |
|
| 113 |
ChargeSession/ |
|
| 114 |
BatteryCheckpointEditorSheetView.swift |
|
| 115 |
ChargeSessionCompletionSheetView.swift |
|
| 116 |
Editors/ |
|
| 117 |
ChargedDeviceEditorSheetView.swift |
|
| 118 |
ChargerEditorSheetView.swift |
|
| 119 |
Library/ |
|
| 120 |
ChargedDeviceLibrarySheetView.swift |
|
| 121 |
Sidebar/ |
|
| 122 |
SidebarChargedDeviceLibraryView.swift |
|
| 123 |
SidebarChargedDevicesSectionView.swift |
|
| 124 |
``` |
|
| 125 | ||
| 126 |
## Refactor Examples |
|
| 127 | ||
| 128 |
- `Connection/` -> `Home/` |
|
| 129 |
- `MeterConnectionTabView` -> `MeterHomeTabView` |
|
| 130 |
- `ConnectionHomeInfoPreviewView` -> `MeterOverviewSectionView` |
|
| 131 |
- `ConnectionPrimaryActionView` -> `MeterConnectionActionView` |
|
| 132 |
- `EditNameView` -> `MeterNameEditorView` |
|
| 133 |
- `MeasurementsView` -> `AppHistorySheetView` |
|
| 134 |
- `RecordingView` -> `ChargeRecordSheetView` |
|
| 135 |
- `ControlView` -> `MeterScreenControlsView` |
|
| 136 | ||
| 137 |
## Decision Rule |
|
| 138 | ||
| 139 |
If a new name makes a teammate look in the right folder on the first try, it is probably a good name. |