#Looking for advice on API design for Zig libraries. ?

1 messages · Page 1 of 1 (latest)

simple glade
#

Hi everyone, I'm fairly new to the language, and I really love it, it's amazing. I want to contribute to the community in one way or another and even if nobody will be using any of my libs I want to make as much libraries as possible as a way to get better at the language. Having said that if I'm going to spend weeks writing modules upon modules I might as well get good advice on idiomatic Zig. Is there some common interface that almost every api should includes ? Is there some canonical ways of naming things ? Or things that most would expect. Because i've read a lot of open source zig code and I can of see a few pattern emerging, but I want to know if there are a few more that I might have missed ? Also if you have any suggestions on ideas of Zig modules that are missing to the ecosystem, I'd like to give it a try !

#

Also if anyone has a few git repo that are worth reading in terms of quality, and overall design in Zig I would really appreciate

desert bramble
#

for project ideas, might look in #1102848376569073664

spare jasper
#

I've grown to use snake_case for functions and variables, and CapitalCamelCase for types.

#

Naming-wise

#

But so long as you pick something and are consistent with it, it shouldn't matter that much

#

API wise it depends a lot on the specifics, what problem is being solved, what your users will need, etc - and how you actually want your API to work.
API design is one of the hardest problems in programming. 🤣
You'd have to tell me more about the context as to what the library tries to accomplish, at least, really.

Some general things are:

  • Make memory management easy; both for yourself and consumers of your code.
    a) Arenas can be extremely handy for this; it often helps to design things so that they specifically work well with arenas.
    Depends on exactly the nature of the API though.
    b) Accepting buffers to write into, also can work well, as allocation can be avoided - which can make things efficient -- though again, it depends a bit.
  • Try to write the usage code first can help a bit in knowing if your API is awkward or not
  • Write some non-trivial examples of how the API can be used which actually does something. (Not just a test for if it works at all or not)
#

One aspect that is often under-utilised I think, in libraries, is:

  • Design the API so that you have a bunch of low-level functions/types which are composed together in order to perform the job.
  • Provide helpers that compose them together for the common path that users would come to your library for.
#

The observation being that you don't know (and ultimately don't control) what your users needs are; only they know that.

#

You should attempt to avoid making assumptions about what the user wants, as much as possible, to help them with that.

#

The job of the library is to provide some functionality, so that they can get done what they wanna get done.

spare jasper
#

So it's like, 3 levels:

  • High level helper functions/types that cover the 80% solution
  • Low level functions/types for if users want a bit more control, or flexibility to their usecase(s).
  • Easy to just take your code and modify it to better cover the user's usecase(s).
foggy crane
#

Excellent advice!