I’m wrapping a java API, specifically Interactive Brokers’ with clojure. You establish a connection to server running on your computer. Then you send messages to the server, and receive messages from it. I’m close to releasing a library that I think improves a lot on the java api.
One thing I’m really struggling with is how to name concepts in my library.
I’ve adapted the Sente style of messages for both incoming messages and outgoing messages.
[<ev-id> <?ev-data>], e.g. [:my-app/some-req {:data "data"}]
Sente calls them events for messages in both directions. This doesn’t feel right in my context. For one, there are incoming messages with the same name as outgoing messages, but which are fundamentally different, for instance there’s a :mylib.request/historical-data
and a mylib.incoming-msg/historical-data
so I need some sort of namespace segment to seperate them and these are what I’m struggling to name.
:mylib.request/x
and :mylib.response/x
doens’t totally feel right because the incoming messages are not necessarily responses, sometimes they come in without a request, such as when the internet connection is lost.
So I’ve been using :mylib.request/x
and :mylib.event/x
but this feels a little awkard too, because there are some times in the code i want to refer internally to both the requests and events, and then what do I call these, what is the term in the hierarchy above these?
Another options I’ve been considering is calling everything a message and using :mylib.msg.in/x
and :mylib.msg.out/x
but in practice I find this awkard, I keep forgetting/having to think for a minute about if “in” refers to coming in to me or going in to the server.
So right now I’m leaning towards :mylib.msg.to/x
and :mylib.msg.from/x
I kind of like how these feel but I haven’t really seen to/from used like this to name things like this, does this seem awkward to anyone?
One important note is that users of the library will not really be exposed to these names in regular usage. Unqualified keywords are used in the api and then qualified internally by the library and used to spec/translate values at boundaries. For example the usage api looks like
(request connection [:historical-data {:arg1 x :arg2 y}])
internally becomes
[:mylib.request/historical-data {:mylib.request.historical-data/arg1 x :mylib.request.historical-data/arg1 y}]
and then these are validated and translated from clojure to the java value the server understands.
Of course I’m overthinking this but I’d prefer to get this stuff to a point I’m happy with before working on documentation, any thoughts or opinions would be appreciated, thanks!