I'm too dumb for Zig's new IO interface

Ai is great at block comments, there is no excuse. Add to that a small anotated usage example written by a human and this whole post would have not existed.

Lack of docs also cripple AI from understanding, so future adoption becomes even more bleak.

If an api or library developer didnt bother doing even bare minimum docs, my confidence in the library drops aswell.

Did they skip testing aswell? Ran the happy path for a day and called it good?

This post sour my interest in zig. Its now obvious to me now why rust took much of its market.

I don't want to read ai slop comments. If you cant be bothered writing docs, I cant be bothered learning to use your library.

I think it is a trade off for between zig's development speed and documentation. It is Pre 1.0, extreme beta mode with lots of breaking changes.

Generally speaking I think it is the right trade off for now. Purely inferring from Andrew and the Zig's team online character as I don't know them in person, I think they do care a lot of DX, things like compiling speed and tools. So I think once 1.0 come I won't be surprised if it will have extremely good documentation as well.

And I would argue, writing good, simple, clear, detailed documentation is actually harder than writing code itself.

Contributions to the Zig language or contributions to software using Zig (the latter is the one the post is about as I understand)?

If so, I believe Zig will stay within a niche. Lower entry barriers allow "script kiddies" to easily start withe language, and they eventually will become leading engineers. Only a few people tend to go straight for the highest practice without "playing around". IMHO the reason, why PHP got so popular (it was not good back then, just very very easy to start with).

I think it is intentional. They don't want to attract low-commitment beginners while the language is heavily changing (and explicitly in beta). Such people will ask questions and ask for documentation but contribute nothing.

Not only, the whole handmade movement puts me off.

It is the anti-intelectualism from Go culture, gone wild against C++, Rust, Swift, anything modern, or even tools, using game engines versus doing the whole computer from scratch for a game.

> The key problem with Zig nowadays is how much of its community and adoption is driven by anti-Rust sentiment. As a result, while Rust puts beginner onboarding and documentation at the center of its culture, as opposed to the “C neckbeard”'s culture, Zig is going the other way around.

Maybe, or maybe the fact that Zig is a small independent project with limited resources has also something to do with it, and this kind of shaming says less about Zig than you'd think.

When I first joined the Zig project, Zig was still using the bootstrap compiler written in C++ that would not free memory (it took more than 4GB to compile the Zig compiler). Some people at the time were asking us to prioritize work on the package manager but Andrew rightfully wanted to prioritize rewriting the compiler instead. In hindsight this was the obviously right decision: a package manager implies that one can very easily add an order of magnitude more code to their project, stressing the performance of the compiler. If we had not prioritized core infrastructure over giving people what they wanted faster, today we would have people complaining that adding a single dependency to their project makes the build impossible to complete.

The Zig project has a huge scope and we are a small independent organization. This makes us extremely nimble and efficient, but it does mean that we need to do things in the order that makes the most sense for the project, not for what the public wants.

The fact that we develop in the open doesn't mean that the language is ready yet.

People that already have the required domain knowledge (and who have a tolerance for breaking changes) will have the opportunity to be early adopters if they wish to do so, others will have to wait for Zig to become more mature. And we do make this clear in releases and all forms of public communication.

We have gone a long way since the bootstrap compiler days, but we are still missing key infrastructure:

- we have a x86_64 custom backend but aarch64 is not complete yet - incremental compilation is showing that we can get instant rebuilds of large projects, but it has missing features and it doesn't work on all platforms yet - we need native fuzzing since AFL keeps regressing everytime a new version of LLVM comes out - for the longest time we haven't had a strong I/O story, now we're finally working on it

The time for paving the road for a new generation of programmers will come (it's in the ZSF mission statement btw), but first we need to finish the plumbing.

This really struck a chord with me. Writing documentation is an act of explaining something to others. Explaining something to others is a great way to test your own understanding. If it's hard to explain to someone else, then maybe it's the wrong design.

If you don't through that exercise, you're much more likely to build confusing, difficult-to-use APIs.

100%.

Similar to how TDD forces you to first figure out the API of your code due to the test code being its first client.

Docs later is an okay approach, when you build something in a closed environment, where the only users know the code inside out.

But when working in open-source and your goal is to have people adopt your software, then it's a bad point and a lazy excuse.

Zig as a whole is half-finished, should it be kept under wraps until it is ready?

There's a reason for the 0.x version number, if you can't live with breaking changes, don't use Zig yet. It's as simple as that.

Because the language is not stable at this point and hasn't reached 1.0?

Are you saying one should never make anything half finished available to the public? This post proves why it is valuable to do so, they are getting valuable feedback and a discussion on hacker news for free.

In serious codebases docs are not an afterthought. There's lots of places where you're expected to add both a new interface and docs together.

[flagged]

So zig isn’t a serious language. It’s just some trash apis thrown together.

If you mean running clang-tidy as a separate build step or ASAN in a different category than other soundness checks?

Compute is getting tight, lots of trends, the age of C++ is winding down gracefully. The age of Zig is emerging delibetately, and the stuff in the middle will end up in the same historical trash bin as everything else in the Altman Era: the misfortunes of losing sight of the technology.

https://github.com/oxidecomputer/omicron/blob/5fd1c35/nexus/...

> low level libraries in Zig, just as it is in C

Did you write any Zig code yet? In terms of enforced correctness in the language (e.g. no integer promotion, no implicit 'dangerous' casts, null-safety, enforced error handling, etc...) and runtime safety (range-, nullptr-, integer-overflow-checks etc...), Zig is much closer to Rust than it is to C and C++.

It "just" doesn't solve static memory safety and some (admittedly important) temporal memory safety issues (aka "use-after-free"), but it still makes it much harder to accidentially trigger memory corruption as a side effect in most situations that C and C++ let slip through via a mix of compile errors and runtime checks (and you get ASAN/UBSAN automatically enabled in debug builds, a debug allocator which detects memory leaks and use-after-free for heap-allocations (unfortunately not for stack allocations), and proper runtime stack traces - things that many C/C++ toolchains are still missing or don't enable by default).

There is still one notable issue: returning a reference to stack memory from a function - this is something that many unexperienced Zig programmers seem to stumble into, especially since Zig's slice syntax looks so 'innocent' (slices look too similar to arrays, but arrays are values, while slices are references - e.g. 'fat pointers') - and which IMHO needs some sort of solution (either a compile time error via watertight escape analysis, or at least some sort runtime check which panics when trying to access 'stale' data on the stack) - and maybe giving slices their own distinct syntax that doesn't overlap with arrays might also help a bit.

> I think the argument is that it is also extremely difficult to write low level libraries in Zig, just as it is in C.

This has been not my experience at all in the ~6 years I've been writing Zig. I started having very little experience writing C (<1000, lines all written while in university) and since day 1 Zig has been a tremendous improvement over it, even back when it was at version 0.4.0.

Web servers, games, and applications, that sort of thing.

Some people definitely do systems programming in, but it's a minority. The std library is not set up for it at all, you need something like rustix, but even that results in very unidiomatic ("unsafe") rust code.

In Zig it's all in the std library by default. Because it's a systems programming language, first and foremost.

Let me answer your question with a question - how do you memory map in rust with the standard library?

In zig it's std.posix.mmap.