From 5b83bf5a16d9026b7868fcac55923a5b6c7cb920 Mon Sep 17 00:00:00 2001
From: Runxi Yu <me@runxiyu.org>
Date: Tue, 16 Sep 2025 20:39:46 +0800
Subject: [PATCH] Update README with philosophical notes

---
 README.md | 39 ++++++++++++++++++++++++++++++++++++++-

diff --git a/README.md b/README.md
index 2c6ce72cfa0279be0943758c257fe3f159065f85..bb92ae8071d206e5c20f84be593c3db7ac82fe2c 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,44 @@
 This module provides various general-purpose data structures for use in the
 Hare programming language.
 
-Functions here typically use `[]u8` keys and `*opaque` values.
+## Note
+
+**The maintainers of Hare would likely not recommend using this library.**
+
+From [Why doesn’t Hare have generics?](https://harelang.org/documentation/faq.html#why-doesn-t-hare-have-generics),
+
+> Our semi-official casual explanation of this choice is that many programs
+> have, at most, one or two really important data structures central to their
+> design (and responsible for their bottlenecks), and because these data
+> structures are important and central to the design, it’s wise for you to
+> implement these yourself so that you can (1) understand them and (2) adapt
+> them to your specific use-case. Optimizing every other data structure that
+> your program makes use of, but which is not bottlenecking your performance,
+> is a premature optimization.
+
+While the above is an explanation of why Hare does not have generics, it serves
+as a general argument against general-purpose data structures, such as those
+implemented in this library. For examples, when a key-value map is needed but
+is not a bottleneck, they may recommend using a simple slice of pairs and
+iterate through them linearly.
+
+We respectfully dissent, because we believe that general-purpose data
+structures can be implemented in a way that is efficient enough for many use
+cases, even if not as efficient as a hand-crafted data structure for each
+specific use case. It is, instead, a premature optimization to hand-craft maps
+for specific use case that would want something better than a linear search.
+Even though hashmaps and tree-based maps could be considered an optimization
+over a linear search, optimization should not be all-or-nothing; an appropriate
+amount of optimization such as using hashmaps in many places, is better than
+having linear searches everywhere where they are slow, and is also better than
+hand-crafting maps for every conceivable use case where linear searches are too
+slow. In practice, many codebases use numerous auxillary maps which share
+similar access patterns but may use differen types. Re-implementing a bespoke
+and non-general-purpose map for each key/value type is a complete waste of
+effort if access patterns are similar.
+
+Also, as a consequence of not having generics, the data structures here are not
+type safe. Structures here typically use `[]u8` keys and `*opaque` values.
 
 ## Contributing
 

-- 
2.48.1