Skip to content

Commit 1e9d298

Browse files
committed
docs: update 'ADR 0001'
1 parent 0464cf2 commit 1e9d298

File tree

2 files changed

+42
-39
lines changed

2 files changed

+42
-39
lines changed

.adrs/0001-choice-between-useless-and-unnecessary-in-rule-naming.md

Lines changed: 0 additions & 39 deletions
This file was deleted.
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# ADR 0001: Choice between "useless", "unnecessary", and "redundant" in Rule Naming
2+
3+
Date: 2025-03-20
4+
5+
Status: Proposed
6+
7+
## Context
8+
9+
In rule naming, the terms "useless", "unnecessary", and "redundant" have been used inconsistently to describe rules that identify code patterns with no functional value. However, practical experience and external precedent (e.g., Their use on <https://react.dev>) indicate that these terms have nuanced differences in meaning:
10+
11+
- **Useless**: Code that serves no purpose and can be safely removed without substitution (e.g., a `fragment` with no children).
12+
- **Unnecessary**: Code that introduces extra complexity and can be simplified without changing the expected behavior (e.g., a `template literal` with no dynamic expressions).
13+
- **Redundant**: Code that repeats functionality already provided elsewhere (e.g., a redundant _state variable_ that can be derived from the existing _state variables_).
14+
15+
The current naming convention of defaulting to `no-useless-*` for many rules risks misalignment with the specificity of the issue being addressed, leading to confusion for users and maintainers.
16+
17+
## Decision
18+
19+
1. **Terminology Guidelines**:
20+
- Use `useless` for code that is **entirely devoid of purpose** and should be deleted.
21+
Example: `no-useless-fragment` (a fragment with no children).
22+
- Use `unnecessary` for code that **can be simplified** without changing behavior.
23+
Example: `no-unnecessary-use-memo` ([an `useMemo` call on a value that is rarely changed](https://react.dev/reference/react/useMemo#should-you-add-usememo-everywhere)).
24+
- Use `redundant` for code that **duplicates existing functionality**.
25+
Example: `no-redundant-state` ([a state variable that can be calculated during render](https://react.dev/learn/choosing-the-state-structure#avoid-redundant-state)).
26+
27+
2. **Alignment with Existing Conventions**:
28+
Follow patterns from <https://react.dev> to ensure familiarity and consistency.
29+
30+
## Consequences
31+
32+
- **Improved Clarity**: Rule names will more accurately signal the nature of the issue, aiding developers in understanding and addressing violations.
33+
- **Consistency**: Alignment with the official React documentation will reduce confusion.
34+
- **Migration Cost**: Existing rules with misaligned names will require updates to documentation, configurations, and potentially codemods for users.
35+
36+
## Alternatives Considered
37+
38+
1. **Uniform Use of one Term**: Using a single term (e.g., `useless`) for all rules. This would simplify naming but would lead to ambiguity and miscommunication about the specific nature of the issues.
39+
40+
## Related ADRs
41+
42+
- None at this time.

0 commit comments

Comments
 (0)