go-cuckoo/adr/001_design_principles.md

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.
   • The README.md and doc.go should reflect these principles.
   • The contributing guide and pull request template should require these principles.
2. The repository should contain a living document, describing the interface differences between go-cuckoo and map.
   • Its construction should uncover any current incongruencies in the interfaces.
   • I should prioritize limiting any incongruencies.
   • The document should be visible from the README.md.
3. An analysis of the familiarity of go-cuckoo's interface should be made.
   • 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.