Compare commits
8
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
3806331768 | ||
|
|
2b610eaab6 | ||
|
|
00ed7c8888 | ||
|
|
b96d47fa1b | ||
|
|
df5a25d349 | ||
|
|
3f77e230a1 | ||
|
|
7bc42e7101 | ||
|
|
56096bd83f |
@@ -0,0 +1,15 @@
|
||||
# Title
|
||||
|
||||
**Status**: <!-- Proposed, accepted, rejected, etc... -->
|
||||
|
||||
## Context
|
||||
|
||||
<!-- What is the issue that we're seeing that is motivating this decision or change? -->
|
||||
|
||||
## Decision
|
||||
|
||||
<!-- What is the change that we're proposing and/or doing? -->
|
||||
|
||||
## Consequences
|
||||
|
||||
<!-- What becomes easier or more difficult to do because of this change? -->
|
||||
@@ -0,0 +1,44 @@
|
||||
# Adopt Congruent and Familiar Design For `go-cuckoo`
|
||||
|
||||
**Status**: Proposed
|
||||
|
||||
## Context
|
||||
|
||||
I built `go-cuckoo`'s API interface without design intent.
|
||||
Up until now, I paid more attention implementing the underlying functionality of the cuckoo hashing.
|
||||
With the fundamentals of the algorithm built, I should revisit the interface.
|
||||
|
||||
The goal of this project was to create an implementation of cuckoo hashing, while adhering to Go's idioms, and being as usable as possible.
|
||||
While the implementation does work, it lacks direction.
|
||||
|
||||
## Decision
|
||||
|
||||
To resolve this, I'm enforcing two new principles onto the contract of `go-cuckoo`:
|
||||
|
||||
- **Congruency**:
|
||||
A `go-cuckoo` table should have the same core functionality as Go's built-in map.
|
||||
|
||||
- **Familiarity**:
|
||||
A `go-cuckoo` table should behave similarly to Go's standard map, so users will intuitively know how to use it.
|
||||
In effect, its users will carry less cognitive load.
|
||||
|
||||
These principles should _guide_ the public interface of `go-cuckoo`.
|
||||
Neither should be treated absolutely, though.
|
||||
The behavior of `go-cuckoo` is distinct from `map`.
|
||||
Do not equate them.
|
||||
|
||||
## Consequences
|
||||
|
||||
1. The repository should support both design principles.
|
||||
- [ ] Update the `README.md` and `doc.go` to reflect these principles.
|
||||
- [ ] Update the contributing guide and pull request template to require these principles are met.
|
||||
2. The repository should contain a living document, describing the interface differences between `go-cuckoo` and `map`.
|
||||
I should prioritize limiting any incongruencies.
|
||||
- [ ] Produce the first draft to uncover any current incongruencies.
|
||||
- [ ] Link the document to the `README.md`.
|
||||
3. Analyze the familiarity of `go-cuckoo`'s current interface.
|
||||
Unlike the analysis of congruency, this should be a one time document.
|
||||
Familiarity is implicit to users, and does not need to be referenced.
|
||||
But, any rationale should be documented in commit messages, or future ADRs.
|
||||
- [ ] Produce the analysis document.
|
||||
- [ ] Resolve any issues found.
|
||||
Reference in New Issue
Block a user