Comment by aDyslecticCrow a day ago
Breaking changes and limited support is one thing. But docs is not something you add at at the end. Lacking docs and Lacking tests is code that should not be released.
They target embedded c market. Limited support and features is expected and common. But being lax with docs and testing is not acceptable.
I fundamentally disagree on code readability. A comment on the function header can save an hour of code reverse engineering for a complex library. Reading code is a last resort, and stale code docs is itself a red flag.
This post itself is a great example. The code is not self explanatory unless you understand the library below. So if this was library code; you would have to reverse through two abstraktion walls to understand it.
And as for high level documentation... it would be very helpful to have that DURING the development process to discuss the implementation, and quickly get people up-to-speed in the plan during code review. Id write that before the code.
I mention tests, because they are 10x more work to write than docs. So if the developer skips out on docs, my trust in their testing is also destroyed.
> But being lax with docs and testing is not acceptable.
First: Those two things are not the same. The Zig stdlib and compiler have tons of tests, and it's actually quite rare to stumble over implementation bugs.
Second: I'd rather take no docs at all than per-function or per-type doc-headers which just repeat what the code does in natural language (and then may quickly get stale). Some parent wrote about generating docs with an LLM which is just a laughably bad idea, since even with perfect results you'll just get a redundant reiteration of what the code below does, just in imprecise human language, it would literally just be redundant noise.
Documentation mostly makes sense up on the systems level to explain high level concepts, not as 'this function does this and that...' level, this information already exists in much more precise form in the source code below the doc header.
But this sort of high level documentation doesn't make sense as long as a project is in the experimentation phase, and Zig is still one big experiment.