[erlang-questions] Request feedback on example project

[zxq9]

On 2016年2月4日 木曜日 16:35:26 Richard A. O'Keefe wrote:
> UUID support in various flavours of Unix is ridiculously spotty,
> so I've been looking for a readable implementation for a while.
> 
> In particular, the support for all of versions 1-5 looks useful;
> the C libraries available to me do not do that.

The use case for version 2 UUIDs seems extremely narrow and better
handled in other ways, imo, but a discussion about how odd it is and
the general lack of any implementations is actually what led me to
write this in the first place. It happily turned out that a UUID
library is an ideal size for me to solicit some feedback on style
and documentation -- so I took advantage of it. I'm really glad I
did.

> I will say that stuffing curly braces around the UUID by default
> is both surprising and unhelpful; it's probably a bad idea for
> there to *be* a default.

This has been mentioned *twice* now. So...

I'm deprecating zuuid:string/0 and zuuid:binary/0 and adding two forms
that have been requested. As someone is already using this in a project
(that was fast... actually overnight) I'll just have to also demonstrate
what version numbers are supposed to mean. v2.0 will lack string/0 and
binary/0. A later version may reintroduce them as an equivalent for the
unbracketed canonical representation.

The price of having users... paid in version numbers.

> The version of Erlang I have installed doesn't support maps.
> I was trying to install 18.2 today but ran into problems (see
> earlier message from me today).  So I cannot compile zuuid.
> (The RestartStrategy is given as a map in zuuid_sup:init/1.)

I don't even like the idea of using maps for this, but the "old
fashioned" tuple type seems to be discouraged in the R18 docs. Meh.

So much for trying to be hip to the new thing. I like my old tuples.
I don't think there is anything in here that doesn't work even with
rather old ERTS releases, so I'm switching this (back) to tuples.
With regard to tuples VS maps for trivial things like this... I almost
feel like its a case of getting a newfangled toy and simply feeling
compelled to use it everywhere.

> Speaking of documentation, while init/1 may be a private
> function, that doesn't mean that someone who isn't highly
> skilled in OTP wouldn't benefit from an explanation of *why*
> the flags and child spec are what they are.

That's a really good point. I remember that being something I had to
take on faith early on myself and really learn later; annoyingly
similar to some other languages -- though in this case its more
about the system than the language.

I've written an explanation in the comments.

> Suppose that getifaddrs() returns a list in which no element
> contains an hwaddr.
> - If the list is entirely empty, {error,no_iface} results.
> - If the list is not empty, {error,no_address} results.
> Why are these different?

Indeed, I failed to explain the difference. That is now remedied.

> I note that the example for get_hw_addr/1 suggests
> eth2, br1, birbr0, wlan0
> as things to look for, none of which are reported on my machine.
> (I have lo0, gif0, stgf0, en0, en1, en2, en3, p2p0, bridge0.)
> Examples that don't work are always confusing.
> What's particularly confusing for the new reader is "where does
> this list of magic alphabet soup come from?  If none of this
> works, is my machine set up wrong, or what?"
> I note that this time, a non-empty list of interface addresses
> that happens not to contain the one you are looking for will be
> reported as no_iface, not no_address.
> 
> "The hardware addressed desired."
> Should that be "address"?

Indeed. I just assumed familiarity with these. I've added a note to
the docs with some references (sort of sloppy, though; not really
satisfied, but at least its touched upon).

> It's probably there somewhere, but I haven't found it, so can I ask
> that every module that can report {error, Reason} should either
> document the Reasons explicitly itself, or point to a documented
> catalogue from which it draws?

Missed this entirely. Added now, on both counts.

> I wanted to report something profound and insightful, but these are
> just a few comparatively unimportant things that bugged me when I
> was reading the code.
> 
> Oh, a layout issue.  I don't like big black blobs (except when I
> write them).  So
> %% wdrwertwertwert
> %% wertwertwertwrt
> %% wretertwertwertew
> -spec frgsdfgdfghsdfg
> asdfasdf(sdfgsdfg) ->
>     ....
> 
> is just a bit too much for me to be comfortable with.  I'd find
> it easier to read with blank line after the %% comment block
> and a blank line after the -spec.
> 
> I find that with my OWN code it's so obvious that packing it
> tightly doesn't impair readability, but with someone else's
> code well-placed blank lines never go amiss.  I can only suppose
> that I'm in error about my own code and that it too could do with
> more blank lines.

*MY* code is always perfectly readable as big, immaculate, unbroken
blocks. Until a few months later. Ugh.

I'm not sure where I stand on the line break issue, really, but since
you mentioned it I'm trying out a line between doc and spec, a line
between spec and definition, and two lines between functions (but no
lines between function clauses -- I already know that confuses me,
especially with un-specced/un-docced functions).

Thanks a lot! If anything else comes to mind, please let me know!

-Craig