And that is why the docs are wiki posts, so that users can edit and improve them.
Explaining it so the author of the article understands why and so that they have a chance to update their article is of greater value than editing it directly as then the author is also aware of why it needed to change thus improving future articles.
Making the change myself would deprive the author of the discussion of why the current is incorrect (e.g .create presented as a general solution while itâs highly context dependent if itâs correct at all with the usual case being that itâs not) and defeat the point of having a forum to discuss it. This is similar to the unreachable discussion as itâs pointless to change it if the author doesnât understand why itâs wrong as there is a high chance that it will be reverted back to the incorrect state later on in addition to the author continuing to give advice based on their old understanding of the problem.
Also, I may be wrong and discussing the topic helps figure that out while another wrong edit doesnât help anyone.
- Iâm not convinced that the
createexample is wrong or misleading. - The section where the examples are listed is titled Possible Workarounds, clearly denoting the non-canonical, non-authoritative, non-single-source-of-truth nature of said examples.
- I donât agree that this is misleading or âleading beginners down the wrong path.â
When you pointed out the possibility of partially uninitialized structures resulting from the comptime default field init method, this was an example of code that indeed cause problems by introducing a subtle bug in a program. Thatâs why I agreed and removed it. In the case of create, I see no such serious problem at all, and indeed it is a possible workaround for the specific problem presenting in the article. So in this case, I respect your opinion, but I donât concur.
1 Like
It concerns program design and while it does ensure the value is initialized it doesnât really take into account the surrounding context (none is given). In zig, most of the time you wouldnât want to use allocator.create(...) as the majority of the time the item youâre allocating heap memory you have more than one of the given item. allocator.create() is there when you need a stable address for a given item (e.g you want to have stable pointers to it) rather than general allocation as youâre often better off just returning the value if you just have a single one.
Thus the above is presenting what would be a design flaw in your program (outside of rare special cases) as a suggestion to the general problem without any futher information about when you should use it which is the problem I have with it. Those learning zig tend to look at articles like this and go âoh, ok, so I add a create function and everything is solvedâ and given thereâs no text on âwhyâ or âwhenâ to use this they usually assume this is the go-to for every situation resulting in many small heap allocated objects which beings with it performance issues, difficult lifetime management, higher memory use (memory fragmentation), etc.
If not removed, at least add a disclaimer that .create(...) is only suitable in a context where you need a stable pointer to this item in particular and that allocating with a container is the typical case in most applications.
Even if this is a possible workaround (maybe âworkaroundâ is also a hint) it would be better to present solutions instead of working around parts of the language. Memory allocation is not something to workaround but rather something you include in your design thus suggesting patterns should always come with design notes, context, etc or it becomes misleading as new users will take it as âthis is how itâs meant to beâ. The goal of the articles is not to workaround the language but rather to help guide new users right? This is the same as telling a new rust user to use Rc in rust when they donât yet understand the borrow checker as this will work but itâs nowhere near correct program design as they never really learn to handle the actual problem nor do they learn when Rc shouldnât be used.
More on the topic:
- Data Oriented Design
- Mike Acton CppCon 2014: Data Oriented Design
- Andrew Kelley Handmade Seattle: Practical DOD
- Memory Fragmentation, your worst nightmare
- Handles are the better pointers
- Pooling
- Malloc is an Antipattern
Also, when it comes to learning resources, that you donât mention is often just as important as that you do. If you present a pattern without context then youâre communicating âthis is suitable in all contextsâ even if itâs not intended to do so. Thus itâs always best to include context and disclaimers such that the reader is reminded that problems do not exist in isolation.
Since you seem to know what code is âcorrectâ âmost of the timeâ and what âthose learning Zigâ tend to think, I invite you to write a Docs article covering all these topics you have mentioned. It would be a comprehensive and valuable learning resource indeed.
3 Likes
But you shouldnât make any language decisions based on them. Theyâ'll learn with experience, and the more you coddle them, the slower theyâll learn. Only a tiny fraction of their career is spend being a beginner.