mvhutz
3e7acb2b51
## Description We need a more directed approach to `go-cuckoo`'s interface. This ADR proposes that direction. ## Changes - Add ADR template. - Add "Adopt Congruent and Familiar Design For `go-cuckoo`" ADR. ## Design Decisions - ~~Put ADRs under `adr/` for more. Because we don't realy have any docs right now, it doesn't make much sense to nest it.~~ ## Checklist - [x] Tests pass - [x] Docs updated Reviewed-on: #26 Co-authored-by: M.V. Hutz <git@maximhutz.me> Co-committed-by: M.V. Hutz <git@maximhutz.me>
2.3 KiB
Adopt Parity and Consistency as Principles For go-cuckoo
Status: Accepted
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:
-
Parity (with
map): Ago-cuckootable should have the same core functionality asmap. By 'core', I meanmap's built-in syntax and functions (e.g.range,m[k]), and themapspackage. Higher parity means users can trust thatgo-cuckoocan do whatmapcan do. -
Consistency (with
map): Ago-cuckootable should behave similarly tomap, so users will intuitively know how to use it. Higher consistency lowers the cognitive load users must carry.
While these principles should guide the interface of go-cuckoo, they should not be absolute.
The behavior of go-cuckoo is distinct from map (e.g. Put can fail; see ErrBadHash), so do not equate them.
Consequences
- The repository should contain a living document, describing the interface differences between
go-cuckooandmap. I should prioritize limiting any disparity. (I already started work on branchdocs/interface-congruency-analysis.)- Produce the first draft to uncover any current disparity.
- Link the document to the
README.md.
- Analyze the consistency of
go-cuckoo's current interface. Unlike the analysis of parity, this should be a one time document. Consistency 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.
- The repository should support both design principles.
As I resolve gaps in parity and consistency, I should feed any reusable heuristics back into the contributing guide.
- State these principles in the
README.mdanddoc.go. - Ground the contributing guide and pull request template in these new principles.
- State these principles in the