danielhenrymantilla / rust-uninit

Read trait fixed to soundly work with uninitalized memory
MIT License
25 stars 2 forks source link

Consider alternate names for `Out` #17

Open kupiakos opened 10 months ago

kupiakos commented 10 months ago

For those unfamiliar with out parameters in other languages like C#, this is an unclear name.

What an Out<T> is, at its core, is a write-only reference to T that can be constructed from &mut T or &mut MaybeUninit<T> (or [MaybeUninit<T>]).

I have a few proposed renaming options for us:

  1. Don't rename it, Out is fine. Brevity is important!
  2. WriteOnly - it's important to note that this is write only since "writeable" often implies "readable". The fact that it has a lifetime implies it's a ref already.
  3. WriteRef - it's important to note that this is a ref.
  4. WriteOnlyRef - all of the advantages of 2️⃣ and 4️⃣ , though long to spell
  5. WRef - short, the W is short for "write", and it's a ref.
  6. WoRef - Write-only ref. Wo is not a well-known acronym I find, but we can start the trend 😄
  7. Wo - Write-only. Extreme brevity 💥

I'm also proposing these options to my team at work to see what they think. So far, Out and WriteOnly + a Wo type alias for brevity are the most popular. Let me know if you have other name proposals as well.

danielhenrymantilla commented 9 months ago
  1. WoLolo, which appeals to Age of Empires players

So, my personal preference here would be:

  1. Start off (potentially) overly verbose but at least explicit, i.e., WriteOnlyRef;
  2. Reëxport a shorter convenience alias, e.g., Out our OutRef.

For reference, I've done something along these lines with:

  1. https://docs.rs/higher-kinded-types/0.1.1/higher_kinded_types/trait.ForLifetime.html
  2. https://docs.rs/higher-kinded-types/0.1.1/higher_kinded_types/index.html#reexports