uucidl · July 15, 2025 14:04 · Oct 16, 2019 · Aug 19, 2019 · Jun 7, 2019 · Dec 8, 2018
diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -27,6 +27,12 @@ other environment in which a single technology has to encompass so wide a span.
 
 I am looking at practicionners not theoretical material.
 
+** Infix vs Prefix
+
+https://simblob.blogspot.com/2019/10/verb-noun-vs-noun-verb.html?m=1
+
+noun verb :: tends to discriminate more than, verb noun. This is interesting in that you want powerful verbs that apply to many nouns, however when you have a noun, you want to see a short list of verbs that apply to it. From specific to generic is better for useability than from generic to specific. See autocomplete.
+
 ** Don Williamson "Anonymizing APIs" antipattern
 
 > I really, really don't like "anonymizing" APIs. They take your context-specific knowledge, throw it away, pack your tiny work item into a big generic pipe, then unpack on the other side with code that has to handle the worst case for each work item.

diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -713,6 +713,12 @@ We're thinking about a major release at some point that groups a bunch of API ch
 every API designer has some regrets, but it's darkly funny even stb_image, with a primary API consisting of one entry point, has That One Thing.
 #+end_quote
 
+** Software Engineering, a practictioner approach by Roger Pressman
+
+He names "patterns of control" which can be useful to characterize an API.
+
+In the sequential pattern of control, the caller hands execution fully over to the module. In the incremental pattern of control, the module and caller alternatively take the execution control. In the parallel pattern of control, the work of the module is concurrent with its caller.
+
 * Books
 
 [[https://www.amazon.com/API-Design-C-Martin-Reddy/dp/0123850037]]
diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -27,6 +27,13 @@ other environment in which a single technology has to encompass so wide a span.
 
 I am looking at practicionners not theoretical material.
 
+** Don Williamson "Anonymizing APIs" antipattern
+
+> I really, really don't like "anonymizing" APIs. They take your context-specific knowledge, throw it away, pack your tiny work item into a big generic pipe, then unpack on the other side with code that has to handle the worst case for each work item.
+
+Example: a canvas drawing API that does not differentiate between transparent and non transparent fills means that the renderer implementer now has to differentiate between the two, because the two cases have very different performance profiles.
+Or something that turns a specific shape into a generic polygon.
+
 ** Randy Gaul APIs and Game Engines
 
 http://www.randygaul.net/wp-content/uploads/2018/02/R.Gaul_APIs_ITCarlow.pdf

diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -696,6 +696,16 @@ Read more at https://news.microsoft.com/features/the-engineers-engineer-computer
 
 https://news.microsoft.com/features/the-engineers-engineer-computer-industry-luminaries-salute-dave-cutlers-five-decade-long-quest-for-quality/#hskvWsfxAHmVR0Qq.97
 
+** Fabian Giesen on stb_image
+
+#+begin_quote
+++number_of_people_who_reported_the_documented_stb_image_behavior_as_a_bug; (It's the "channels_in_file" output parameter. The #1 API regret in all of the stb libraries, but fixing it would break backwards compat, so @nothings and me have shied away from it.)
+
+We're thinking about a major release at some point that groups a bunch of API changes (including removing some of the more obscure formats, getting rid of the globals for error reporting, and cleaning up the currently messy 8-bit/16-bit/float situation), but this is the #1 thing.
+
+every API designer has some regrets, but it's darkly funny even stb_image, with a primary API consisting of one entry point, has That One Thing.
+#+end_quote
+
 * Books
 
 [[https://www.amazon.com/API-Design-C-Martin-Reddy/dp/0123850037]]
diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -590,6 +590,14 @@ For example, a programming language is a well defined interface, to reusable com
 
 * Ideas
 
+** Useability
+
+Useability is how well (speed, effort) an user can achieve a goal, within a certain context.
+
+Ex: "Given that I don't know what to find, and want to search the internet, google's search, with its single text entry and quick results gives me an effortless and quick list of potentially interesting web links"
+
+** Properties of APIs
+
 | Bad         | Good             |                 |
 |-------------+------------------+-----------------|
 | Opaque data | Transparent data | Efficient Basis |

diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -27,6 +27,10 @@ other environment in which a single technology has to encompass so wide a span.
 
 I am looking at practicionners not theoretical material.
 
+** Randy Gaul APIs and Game Engines
+
+http://www.randygaul.net/wp-content/uploads/2018/02/R.Gaul_APIs_ITCarlow.pdf
+
 ** Code Podcast: Don't Make Me Write UI
 
 [[https://soundcloud.com/podcastcode/6-dont-make-me-write-ui]]

diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -327,6 +327,8 @@ http://timperrett.com/2016/11/12/frameworks-are-fundimentally-broken/
 
 Reading https://twitter.com/antirez/status/958028135605383169
 
+See Rax api at: [[https://github.com/antirez/rax]]
+
 #+begin_quote
 After delivering a shitty API like Redis’s dict.c hash table,
 this time I did my homework well and the rax.c (radix tree) API is really

diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -325,7 +325,7 @@ http://timperrett.com/2016/11/12/frameworks-are-fundimentally-broken/
 
 ** Antirez on Rax vs Dict
 
-** TODO Reading https://twitter.com/antirez/status/958028135605383169
+Reading https://twitter.com/antirez/status/958028135605383169
 
 #+begin_quote
 After delivering a shitty API like Redis’s dict.c hash table,

diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -323,6 +323,104 @@ http://timperrett.com/2016/11/12/frameworks-are-fundimentally-broken/
 
 [[https://www.sebastiansylvan.com/post/matrix_naming_convention/]]
 
+** Antirez on Rax vs Dict
+
+** TODO Reading https://twitter.com/antirez/status/958028135605383169
+
+#+begin_quote
+After delivering a shitty API like Redis’s dict.c hash table,
+this time I did my homework well and the rax.c (radix tree) API is really
+pleasant to use.
+#+end_quote
+
+Dict API:
+
+#+begin_src c
+#if 0
+// Macros:
+dictFreeVal(d, entry)
+dictSetVal(d, entry, _val_)
+dictSetSignedIntegerVal(entry, _val_)
+dictSetUnsignedIntegerVal(entry, _val_)
+dictSetDoubleVal(entry, _val_)
+dictFreeKey(d, entry)
+dictSetKey(d, entry, _key_) 
+dictCompareKeys(d, key1, key2)
+dictHashKey(d, key)
+dictGetKey(he)
+dictGetVal(he)
+dictGetSignedIntegerVal(he)
+dictGetUnsignedIntegerVal(he)
+dictGetDoubleVal(he)
+dictSlots(d)
+dictSize(d)
+bool dictIsRehashing(d)
+#endif
+
+dict *dictCreate(dictType *type, void *privDataPtr);
+int dictExpand(dict *d, unsigned long size);
+int dictAdd(dict *d, void *key, void *val);
+dictEntry *dictAddRaw(dict *d, void *key, dictEntry **existing);
+dictEntry *dictAddOrFind(dict *d, void *key);
+int dictReplace(dict *d, void *key, void *val);
+int dictDelete(dict *d, const void *key);
+dictEntry *dictUnlink(dict *ht, const void *key);
+void dictFreeUnlinkedEntry(dict *d, dictEntry *he);
+void dictRelease(dict *d);
+dictEntry * dictFind(dict *d, const void *key);
+void *dictFetchValue(dict *d, const void *key);
+int dictResize(dict *d);
+dictIterator *dictGetIterator(dict *d);
+dictIterator *dictGetSafeIterator(dict *d);
+dictEntry *dictNext(dictIterator *iter);
+void dictReleaseIterator(dictIterator *iter);
+dictEntry *dictGetRandomKey(dict *d);
+unsigned int dictGetSomeKeys(dict *d, dictEntry **des, unsigned int count);
+void dictGetStats(char *buf, size_t bufsize, dict *d);
+uint64_t dictGenHashFunction(const void *key, int len);
+uint64_t dictGenCaseHashFunction(const unsigned char *buf, int len);
+void dictEmpty(dict *d, void(callback)(void*));
+void dictEnableResize(void);
+void dictDisableResize(void);
+int dictRehash(dict *d, int n);
+int dictRehashMilliseconds(dict *d, int ms);
+void dictSetHashFunctionSeed(uint8_t *seed);
+uint8_t *dictGetHashFunctionSeed(void);
+unsigned long dictScan(dict *d, unsigned long v, dictScanFunction *fn, dictScanBucketFunction *bucketfn, void *privdata);
+uint64_t dictGetHash(dict *d, const void *key);
+dictEntry **dictFindEntryRefByPtrAndHash(dict *d, const void *oldptr, uint64_t hash);
+#+end_src
+
+Rax API
+#+begin_src c
+/* A special pointer returned for not found items. */
+extern void *raxNotFound;
+
+rax *raxNew(void);
+int raxInsert(rax *rax, unsigned char *s, size_t len, void *data, void **old);
+int raxRemove(rax *rax, unsigned char *s, size_t len, void **old);
+void *raxFind(rax *rax, unsigned char *s, size_t len);
+void raxFree(rax *rax);
+void raxFreeWithCallback(rax *rax, void (*free_callback)(void*));
+void raxStart(raxIterator *it, rax *rt);
+int raxSeek(raxIterator *it, const char *op, unsigned char *ele, size_t len);
+int raxNext(raxIterator *it);
+int raxPrev(raxIterator *it);
+int raxRandomWalk(raxIterator *it, size_t steps);
+int raxCompare(raxIterator *iter, const char *op, unsigned char *key, size_t key_len);
+void raxStop(raxIterator *it);
+int raxEOF(raxIterator *it);
+void raxShow(rax *rax);
+uint64_t raxSize(rax *rax);
+#+end_src
+
+One aspect that makes it good, is that we can see this API apply directly to a
+hash table like dict almost out of the box. As long as the user is willing to
+convert their key types to bytes. Some may consider writing these bytes as too
+expensive, however I'd argue it's easier to get bad performance out of
+injecting equality and hashing callbacks into a hash table. The hashtable
+*has* to be able to compare for equality, afterall.
+
 ** Flutter Design Principles
 
 @url: https://flutter.io/design-principles/#introduction

diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -275,6 +275,7 @@ http://www.cl.cam.ac.uk/~srk31/research/talks/kell16operating-slides.pdf
 
 ** Butler W. Lampson, Hints for Computer System Design
 
+https://www.microsoft.com/en-us/research/publication/hints-for-computer-system-design/
 https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/acrobat-17.pdf
 
 ** Parnas D.L. On The Criteria To Be Used in Decomposing Systems Into Modules, Comm. acm 15 12, dec 1972 p 1053-1058

diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -274,7 +274,8 @@ http://st.inf.tu-dresden.de/files/teaching/ss10/cbse/01-introduction.pdf
 http://www.cl.cam.ac.uk/~srk31/research/talks/kell16operating-slides.pdf
 
 ** Butler W. Lampson, Hints for Computer System Design
-http://research.microsoft.com/en-us/um/people/blampson/33-Hints/WebPage.html
+
+https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/acrobat-17.pdf
 
 ** Parnas D.L. On The Criteria To Be Used in Decomposing Systems Into Modules, Comm. acm 15 12, dec 1972 p 1053-1058
 

diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -426,6 +426,27 @@ Hrm, I vaguely remember the C++ proposal you're referring to. I don't think it w
 <@matt_dz> Oct 9
 A couple, most recent in 2015 (http://wg21.link/P0029 ) and 2016 (PDF: http://wg21.link/P0199 ); latter withdrawn: https://botondballo.wordpress.com/2016/07/06/trip-report-c-standards-meeting-in-oulu-june-2016/ ….
 
+** On Drag And Drop APIs And Their Generality
+
+@url: https://twitter.com/ocornut/status/941627778910380032
+#+begin_quote
+<Omar Cornut> dear imgui: figuring out how to interface with Windows drag and drop, and it turns out that when using WM_DROPFILES it is trivial but super limited, and anything else seems like pain.
+
+<Leonard Ritter> the windows drag & drop API seems really weird until you implement your own and discover all these corner cases and go "oh. okay. now i get it". the GTK one is just as crazy. For my own imgui-based editor I built a drag & drop system that was purely internal, and that alone got fairly complex already. it's like a network protocol that goes "i have these formats to drop, which one is fine?" -- "these are fine" -- "can i drop this one?" -- "you may" And because, for the desktop context, it's also IPC, you need mimetypes or some other global enumerator so y'all understand each other.
+
+<Leonard Ritter> In an earlier windows-based UI for an audio app i ended up using the d&d system for all kinds of stuff (including a dsp node editor) because it was so versatile.
+
+<Omar Cornut> What's annoying is there are so few good examples of how to support Win32 DND in your app, and once you get past WM_DROPFILES you have to do the whole thing.
+I was wondering if we can just somehow more easily implement a IDropTarget to get a better WM_DROPFILES with preview.
+
+<Omar Cornut> There's a beta drag and drop api in imgui master if you want to check it out for suggestions (its basically 6 functions). It's missing demos but there are a few uses of it in the code.
+
+<Omar Cornut> Drag target can compare data format (which are essentially strings in dear imgui land). The main thing that missing now are
+A) the possibility to transport multiple data formats simultaneously
+B) the possibility for the source to compute the payload later (e.g. on drop)
+
+#+end_quote
+
 ** Slug (Decoupling Allocations)
 
 https://twitter.com/EricLengyel/status/938590610604175360

diff --git a/00-notes-about-APIs.org b/00-notes-about-APIs.org
@@ -426,6 +426,28 @@ Hrm, I vaguely remember the C++ proposal you're referring to. I don't think it w
 <@matt_dz> Oct 9
 A couple, most recent in 2015 (http://wg21.link/P0029 ) and 2016 (PDF: http://wg21.link/P0199 ); latter withdrawn: https://botondballo.wordpress.com/2016/07/06/trip-report-c-standards-meeting-in-oulu-june-2016/ ….
 
+** Slug (Decoupling Allocations)
+
+https://twitter.com/EricLengyel/status/938590610604175360
+
+#+begin_quote
+<Eric Lengyel> Slug was designed to have no dependencies whatsoever. It doesn't make calls into anything external to itself, including the standard library, any rendering API, and the operating system. It doesn't even allocate memory.
+
+<Gustavo Samour> The API gives you the buffer size, you allocate, and then pass in the pointers back to the API
+
+<Eric Lengyel> Same goes for vertex buffers. The CountSlug() function tells you how much space you need to allocate for the BuildSlug() function to fill with vertex and triangle data. (Slug does not use callback functions to perform allocations.)
+
+<Dale Kim> I feel that this style of API needs to have more visibility. A lot of folks see a library as code that does something for you, but many libraries do this by also taking away some of your control. Memory being owned by the library is a common example.
+
+Whether or not the API controls you or you control the API is a central issue I see in many problematic systems.  In most cases, you want the caller to retain as much control as possible.
+
+<Tom Forsith> It's OK to ship with defaults to do those things. Granny is the same - if you do nothing, it uses a bunch of standard OS calls. But you can override them easily, either by callback or pre-emption.
+
+<Bryan McNett> even then, i like my libraries to treat allocations as special events, only to be done predictably and rarely.
+
+<Tom Forsith> Agreed. "Create" should be in the name of the function, etc.
+#+end_quote
+
 * Succesful Interfaces
 
 - MIDI

diff --git a/notes-about-APIs.org → 00-notes-about-APIs.org b/notes-about-APIs.org → 00-notes-about-APIs.org
diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -189,6 +189,12 @@ concerns lies. And that's been very helpful. Everytime I don't do this
 I come to regret this because I generally end up writing that
 subsystem multiple times anyway.
 
+** Towards a Theory of Software Design by Daniel Jackson
+
+[[https://youtu.be/cNe6g0qczxE]]
+
+Of particular interest its categorization of bad aspects, bad applications of concepts at the design stage, and its critique of existing software designs, including git.
+
 ** [[https://www.youtube.com/watch?v=ZQ5_u8Lgvyk][Designing and Evaluating Reusable Components]] by Casey Muratori
 
 See my "Commentary And Notes" notebook.

diff --git a/ZZ_Mu_API.md b/ZZ_Mu_API.md
@@ -0,0 +1,79 @@
+[[https://github.com/uucidl/pre.uumu]]
+
+Implementing Per Vognsen's Mu API
+
+Per Vognsen designed the [Mu API](xxxx_mu.h) as an alternative to libraries like SDL,
+SML. I find myself agreeing with many of its design decisions.
+
+He documented it at:
+- @url: https://gist.github.com/pervognsen/6a67966c5dc4247a0021b95c8d0a7b72 (code as of the stream 2)
+- @url: https://www.youtube.com/watch?v=NG_mUhc8LRw
+- @url: https://www.youtube.com/watch?v=pAIdfsT7-EU
+
+His goals:
+- minimal platform layer for multimedia apps (in terms of binary/source size)
+- not industrial-strengh, but excellent for small apps
+- experiment with API design:
+  + good, ritual-free, defaults
+  + eschews the many granular calls these libraries tend to have to
+    set it up or get information from it
+  + instead, provide data in/out through datastructure and a minimal set of functions
+  + dialogue between the app and the library as if the library was a
+  resumable coroutine, to minimize callbacks, which disrupt normal
+  code flow
+
+- extension API with media file loading (image, sound, video)
+
+This is achieved with a global datastructure, whose entries serve as
+much as possible as both input and output.
+
+Other principles: 
+
+Precompute redundant data that is most often useful to users, rather
+than doing it lazilly and potentially too often. Even if that's
+increasing the surface area of the API.
+
+Provide state of controls rather than exposing an event queue to its
+users, since since multimedia applications would anyway have to
+sample/refresh at a high enough rate anyway.
+
+In cases where naïve state-capture would lose events, such as for text,
+the API prepares buffers of prepared data representing the aggregate
+input between two frames.
+
+Compromises:
+
+As of stream #2, audio has been implemented via a callback, pulling
+samples regularly from the high priority audio thread.
+
+Experiments to try:
+
+- The input/output struct is plain old data (if you except the
+  platform specific handles) ; which means it should be trivial to
+  record sequence of values to replay back the application eventually.
+
+Some other personal comments:
+
+A push API for audio is certainly possible, however I personally think
+if it make sense, it should prevent gaps in audio as the result of a
+late frame. It does simplify the usual, simple cases because it
+removes the need for thread-safe code.
+
+Another comment I can make is that the choice of int16_t for audio
+samples, while convenient for mixing in samples coming from audio
+files, make synthesis cases less natural. It's easier and less error
+prone to use float within the 0..1 interval as a generic
+representation of audio samples.
+
+Data-oriented APIs lead to this quite nice low ritual style. 
+
+If there's one negative thing about it, it's that we are used to think
+in terms of API breakage on the basis of an API's functions, however
+people are not used to detect and document API changes due to
+data changes. This might be why a lot of APIs chose instead to use
+opaque data types and lots of functions.
+
+If however one thinks about the larger issue of ABI compatibility
+then it would be a good idea to invest in tooling to detect data
+changes anyway, and the difference disappears.
+
diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -473,6 +473,16 @@ In the book see his example of the egg as an ideal form perfectly adapted to its
 A first principle of construction: on no account allow the engineering to dictate the building’s form . . . . never modify the social spaces to conform to the engineering structure of the building.
 –Christopher Alexander
 
+** Tom Forsyth
+
+"Abstraction"
+
+https://twitter.com/tom_forsyth/status/924692979721281537
+
+#+begin_quote
+My rule is - when writing at layer X, if you can't easily say what the layer below looks like, you've abstracted too far.
+#+end_quote
+
 * Usage
 
 Traditional software engineering wisdom says

diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -246,6 +246,16 @@ So I have a public function and want to add a bool parameter to it. Other soluti
 
 https://www.youtube.com/watch?v=heh4OeB9A-c
 
+** Arvid Gerstmann
+@url: https://twitter.com/ArvidGerstmann/status/918757328920473600
+
+
+<Avid Gerstmann>
+I said it before and I'll say it again: ZeroMQ is the gold standard of API design. Super simple C API, yet incredibly powerful: http://api.zeromq.org/ 
+The guide is a good read, although quite long: http://zguide.zeromq.org/page:all 
+
+Yes, it's C, but it's easy to built your own C++'ey abstraction on top of it, like you see fit. Many C++ APIs are too opinionated, or use STL. ZMQs C API is low-level & flexible. I dislike having a high-level API & prefer building it myself. ZeroMQ also gets this right. They offer CZMQ, a separate high-level library, wrapping the low-level library & providing a nice API.
+
 ** Butler W. Lampson Software Components, Only the Giant Survive
 
 http://research.microsoft.com/en-us/um/people/blampson/70-SoftwareComponents/70-SoftwareComponents.htm

diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -345,6 +345,44 @@ ex: low-level construction of executable code from unsafe/user input pieces
 
 When wrapping another API, faithfully wrap the complete API so as to minimize surprises and avoid creating integration surprises.
 
+** Kiwi Guide To APIs
+
+@url: https://code.kiwi.com/code-design-principles-for-public-apis-of-modules-6a43aaf26624
+@title: Code Design Principles for Public APIs of Modules
+
+Main actions on a module:
+- Creation from scratch
+- Redesign
+
+Heuristics
+
+Names
+
+Remove anything that appears unnecessary (information compression) .. without going as far as hurting redability.
+
+Example of a name that can be shortened, kw.booking.additional_booking_management could be better written kw.booking.additional_booking, as "management" does not appear to contribute much meaning.
+
+Goals for better names:
+- legible useage code, emphasizing its own logic (names that are too long might disrupt legibility of the useage code)
+- names that are easy to be kept consistent (i.e. don't invite variations)
+
+Insights for better APIs
+- how many engineers would maintain that module
+- how many engineers would commonly write code using that module
+- how frequently code using this API might be read over time (times/day)
+- how long might this module be used
+- consider what the user will see
+
+This should help you decide the level of quality this API and implementation should be at.
+
+Before making an implementation clean, think about the user first, and make the API clean. Write tests, prototype useage code.
+
+
+
+Procedures
+- keep number of positional parameters small (< 3)
+- procedures are designed to work on data (if the procedure of a verb, its object), so design/specify that
+
 ** Hashing API
 
 <@pkhuong> Oct 9 Reading Fluent Python… does the official Python documentation really recommend hashing objects by combining their fields' hashes with xor?

diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -305,6 +305,46 @@ http://timperrett.com/2016/11/12/frameworks-are-fundimentally-broken/
 
 [[https://www.sebastiansylvan.com/post/matrix_naming_convention/]]
 
+** Flutter Design Principles
+
+@url: https://flutter.io/design-principles/#introduction
+@title: Flutter Design Principles
+
+Breaking API changes are treated as specific items worthy of attention. Proposals are written and summarized.
+- Justification is made
+- A migration path from old to new code is described
+- Contact for supporting people to move old to new API
+
+Weighting of API stability versus benefits will determine whether the breaking change is to be made.
+
+Transition period by way of annotating old code as deprecated is to be introduced. (using tags such as @escape{@deprecated('Description')})
+
+# API Design
+
+1. Avoid hard to maintain data-retention/duplication
+
+@quote{There should be no objects that represent live state that reflects some other state, since they are expensive to maintain. e.g. no HTMLCollection}
+
+I.e. they discourage data-retention, as it requires synchronization between layers. HTMLCollection
+
+2. Easy access implies cheap access
+
+If something is implemented via what looks syntactically cheap, it should also be cheap.
+
+3. Expensive operations should not be exposed as synchronous procedure calls
+
+4. APIs should be arranged in "physical" levels.
+
+- Convenience APIs layered on top of lower-level APIs
+- Scope of each level is made as narrow as possible
+
+5. Unsafe constructs are not promoted as regular APIs
+ex: low-level construction of executable code from unsafe/user input pieces
+
+6. Adapter APIs should be complete
+
+When wrapping another API, faithfully wrap the complete API so as to minimize surprises and avoid creating integration surprises.
+
 ** Hashing API
 
 <@pkhuong> Oct 9 Reading Fluent Python… does the official Python documentation really recommend hashing objects by combining their fields' hashes with xor?

diff --git a/sh-im-ui-an-api-study.org b/sh-im-ui-an-api-study.org
@@ -142,4 +142,10 @@ As you cross boundary layers there might be a tendency to notice that:
 ```
 A_0 (db1)
 A_1 (db1) -> add/remove events -> B_1 -(diff w/ B_0)-> add/remove operations -> C_1
-```
+```
+
+* IM for physics
+
+http://chipmunk-physics.net/forum/viewtopic.php?t=1434
+http://twvideo01.ubm-us.net/o1/vault/gdc09/slides/gdc09_insomniac_physics.pdf
+https://github.com/erwincoumans/PhysicsEffects
diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -321,7 +321,7 @@ I assume you also hash in the class name :p
 
 I've always thought that hash methods should return an opaque hash_t type, so you aren't even tempted to do this kind of crap.
 
-I think the right interface for extensible hashing is closer to serialising data to a stream (that happens to hash its input bytes). I saw a C++ standard proposal like that; I don't know what happened to it.
+<@pervognsen> Oct 9 I think the right interface for extensible hashing is closer to serialising data to a stream (that happens to hash its input bytes). I saw a C++ standard proposal like that; I don't know what happened to it.
 
 <@pervognsen> Oct 9 Yeah, I was about to correct myself. You need that for streaming. Then you just provide variadic helpers for the combiners. And it lets you distinguish internal hash state vs final hash value.
 

diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -307,7 +307,8 @@ http://timperrett.com/2016/11/12/frameworks-are-fundimentally-broken/
 
 ** Hashing API
 
-<@pkhuong> Oct 9 Reading Fluent Python… does the official Python documentation really recommend hashing objects by combining their fields' hashes with xor? :|
+<@pkhuong> Oct 9 Reading Fluent Python… does the official Python documentation really recommend hashing objects by combining their fields' hashes with xor?
+
 <@pervognsen> Oct 9 Huh? I've always just hashed a tuple of the fields...
 
 I've definitely seen recommendations like that in various Java books, sadly, but Python makes it so easy to just hash a tuple.

diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -305,6 +305,32 @@ http://timperrett.com/2016/11/12/frameworks-are-fundimentally-broken/
 
 [[https://www.sebastiansylvan.com/post/matrix_naming_convention/]]
 
+** Hashing API
+
+<@pkhuong> Oct 9 Reading Fluent Python… does the official Python documentation really recommend hashing objects by combining their fields' hashes with xor? :|
+<@pervognsen> Oct 9 Huh? I've always just hashed a tuple of the fields...
+
+I've definitely seen recommendations like that in various Java books, sadly, but Python makes it so easy to just hash a tuple.
+
+Incidentally, one of my favorite general tricks is to exploit tuple isomorphisms for boilerplate code like that.
+
+<@pkhuong> Oct 9 For sure. Much easier than writing our all 6 comparator methods by hand (:
+
+I assume you also hash in the class name :p
+
+I've always thought that hash methods should return an opaque hash_t type, so you aren't even tempted to do this kind of crap.
+
+I think the right interface for extensible hashing is closer to serialising data to a stream (that happens to hash its input bytes). I saw a C++ standard proposal like that; I don't know what happened to it.
+
+<@pervognsen> Oct 9 Yeah, I was about to correct myself. You need that for streaming. Then you just provide variadic helpers for the combiners. And it lets you distinguish internal hash state vs final hash value.
+
+I prefer the "fold/append/mix into hash state" API for a systems programming language since it doesn't involve other intermediate objects.
+
+Hrm, I vaguely remember the C++ proposal you're referring to. I don't think it was ratified, but I recall it used the streaming style.
+
+<@matt_dz> Oct 9
+A couple, most recent in 2015 (http://wg21.link/P0029 ) and 2016 (PDF: http://wg21.link/P0199 ); latter withdrawn: https://botondballo.wordpress.com/2016/07/06/trip-report-c-standards-meeting-in-oulu-june-2016/ ….
+
 * Succesful Interfaces
 
 - MIDI

diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -406,4 +406,8 @@ Darryl Havens (responsible for the I/O system on NT)
 Read more at https://news.microsoft.com/features/the-engineers-engineer-computer-industry-luminaries-salute-dave-cutlers-five-decade-long-quest-for-quality/#ydU2bC61j8j51kq6.99
 #+end_quote
 
-https://news.microsoft.com/features/the-engineers-engineer-computer-industry-luminaries-salute-dave-cutlers-five-decade-long-quest-for-quality/#hskvWsfxAHmVR0Qq.97
+https://news.microsoft.com/features/the-engineers-engineer-computer-industry-luminaries-salute-dave-cutlers-five-decade-long-quest-for-quality/#hskvWsfxAHmVR0Qq.97
+
+* Books
+
+[[https://www.amazon.com/API-Design-C-Martin-Reddy/dp/0123850037]]
diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -267,6 +267,18 @@ https://www.cs.umd.edu/class/spring2003/cmsc838p/Design/criteria.pdf
 
 ** Britton, K..H, et al. A procedure for designing abstract interfaces for device interface modules. Proc. 5th Int’l Conf. Software Engineering, ieee Computer Society order no. 332, 1981, pp 195-204.
 
+** On compatibility layers
+
+"The people who rely on the compat layers don't 
+care enough to maintain it. The people who work 
+on the mainline system don't care about the compat 
+layers because they don't use them. The cultures 
+aren't aligned in the same direction. 
+Compat layers 
+rot very quickly
+.
+” – Theo De Raadt 
+
 ** Roy Fielding Architectural Styles and the Design of Network-based Software Architectures
 
 aka the REST API paper

diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -277,6 +277,10 @@ aka the REST API paper
 
 Also notes about reuse's failure.
 
+** Monocipher write-up
+
+http://loup-vaillant.fr/articles/implemented-my-own-crypto
+
 ** API Design Tips For Libraries by André Staltz 
 
 http://staltz.com/api-design-tips-for-libraries.html

diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -285,6 +285,10 @@ http://staltz.com/api-design-tips-for-libraries.html
 
 http://timperrett.com/2016/11/12/frameworks-are-fundimentally-broken/
 
+* Example of the value of naming conventions
+
+[[https://www.sebastiansylvan.com/post/matrix_naming_convention/]]
+
 * Succesful Interfaces
 
 - MIDI

diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -375,4 +375,15 @@ https://lwn.net/Articles/336262/
 
 ** problem with the supposed to be "secure" extensions to traditional C functions
 
-http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1967.htm
+http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1967.htm
+
+** Dave Cutler & Darryl Havens
+
+Darryl Havens (responsible for the I/O system on NT)
+
+#+begin_quote
+“If you spend that amount of time designing something and you have a spec that gives you every single API [application programming interface], what its inputs are, what its outputs are, you pretty much know how the thing is going to work,” Havens said. “So I actually typed in the code for the entire I/O system in three weeks. That’s how well-designed it was.  By the time I sat down to write the code, I already pretty much knew how it was going to work.”
+Read more at https://news.microsoft.com/features/the-engineers-engineer-computer-industry-luminaries-salute-dave-cutlers-five-decade-long-quest-for-quality/#ydU2bC61j8j51kq6.99
+#+end_quote
+
+https://news.microsoft.com/features/the-engineers-engineer-computer-industry-luminaries-salute-dave-cutlers-five-decade-long-quest-for-quality/#hskvWsfxAHmVR0Qq.97
diff --git a/notes-about-APIs.org b/notes-about-APIs.org
@@ -371,4 +371,8 @@ Levels:
 
 ** Problem with middle layers in the Linux kernel
 
-https://lwn.net/Articles/336262/
+https://lwn.net/Articles/336262/
+
+** problem with the supposed to be "secure" extensions to traditional C functions
+
+http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1967.htm
No results found