mvhutz
8720204298
CI / Check PR Title (pull_request) Successful in 44s
CI / Makefile Lint (pull_request) Successful in 1m18s
CI / Go Lint (pull_request) Successful in 1m30s
CI / Markdown Lint (pull_request) Successful in 48s
CI / Unit Tests (pull_request) Successful in 1m19s
CI / Fuzz Tests (pull_request) Successful in 1m50s
CI / Mutation Tests (pull_request) Successful in 1m32s
47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
# 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 `map`.
|
|
By 'core', I mean `map`'s built-in syntax and functions (e.g. `range`, `m[k]`), and the `maps` package.
|
|
|
|
- **Familiarity**:
|
|
A `go-cuckoo` table should behave similarly to `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` (e.g. `Put` can fail; see `ErrBadHash`).
|
|
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.
|
|
(I already started work on branch `docs/interface-congruency-analysis`.)
|
|
- [ ] 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.
|