# 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`.
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.